@quazardous/quarkernel-react 2.1.0

package/README.md

@@ -0,0 +1,144 @@
+# @quazardous/quarkernel-react
+
+React 18+ bindings for QuarKernel - Context provider and hooks with auto-cleanup.
+
+## Installation
+
+```bash
+npm install @quazardous/quarkernel @quazardous/quarkernel-react
+```
+
+## Features
+
+- **KernelProvider**: Context provider for dependency injection
+- **useKernel()**: Access kernel anywhere in tree
+- **useOn()**: Register listener with auto-cleanup on unmount
+- **useEventState()**: Reactive state from events
+- **Type-safe**: Full TypeScript support
+- **SSR-safe**: Warns on server-side access
+
+## Usage
+
+### Basic Setup
+
+```tsx
+import { createKernel } from '@quazardous/quarkernel';
+import { KernelProvider } from '@quazardous/quarkernel-react';
+
+const qk = createKernel();
+
+function App() {
+  return (
+    <KernelProvider kernel={kernel}>
+      <MyComponent />
+    </KernelProvider>
+  );
+}
+```
+
+### useKernel()
+
+Access kernel instance from any component:
+
+```tsx
+import { useKernel } from '@quazardous/quarkernel-react';
+
+function MyComponent() {
+  const qk = useKernel();
+
+  const handleClick = () => {
+    qk.emit('button:clicked', { timestamp: Date.now() });
+  };
+
+  return <button onClick={handleClick}>Click me</button>;
+}
+```
+
+### useOn()
+
+Register listener with automatic cleanup on unmount:
+
+```tsx
+import { useOn } from '@quazardous/quarkernel-react';
+
+function Notifications() {
+  useOn('notification:new', (event) => {
+    console.log('New notification:', event.data);
+  });
+
+  // Listener auto-removed when component unmounts
+  return <div>Listening for notifications...</div>;
+}
+```
+
+### useEventState()
+
+Reactive state derived from events:
+
+```tsx
+import { useEventState } from '@quazardous/quarkernel-react';
+
+function Counter() {
+  const count = useEventState('counter:updated', 0, (event) => event.data.value);
+
+  return <div>Count: {count}</div>;
+}
+```
+
+### Wildcard Patterns
+
+```tsx
+import { useOn } from '@quazardous/quarkernel-react';
+
+function UserTracker() {
+  useOn('user:*', (event) => {
+    console.log('User event:', event.name, event.data);
+  });
+
+  return null;
+}
+```
+
+## API
+
+### `<KernelProvider kernel={kernel}>`
+
+Context provider for kernel instance.
+
+**Props:**
+- `kernel`: Kernel instance (required)
+- `children`: React children
+
+### `useKernel()`
+
+Hook to access kernel from context.
+
+**Returns:** Kernel instance
+
+**Throws:** `KernelProviderError` if used outside provider
+
+### `useOn(event, handler, options?)`
+
+Register event listener with auto-cleanup.
+
+**Parameters:**
+- `event`: Event name or wildcard pattern
+- `handler`: `(event, ctx) => void | Promise<void>`
+- `options`: Listener options (id, after, priority)
+
+**Returns:** Unsubscribe function
+
+### `useEventState(event, initial, selector?)`
+
+Reactive state from events.
+
+**Parameters:**
+- `event`: Event name to listen for
+- `initial`: Initial state value
+- `selector`: Optional `(event) => T` to extract value
+
+**Returns:** Current state value
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,107 @@
+'use strict';
+
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/KernelProvider.tsx
+var KernelContext = react.createContext(null);
+function KernelProvider({
+  kernel,
+  children
+}) {
+  return /* @__PURE__ */ jsxRuntime.jsx(KernelContext.Provider, { value: kernel, children });
+}
+var KernelProviderError = class extends Error {
+  constructor() {
+    super(
+      "useKernel must be used within a KernelProvider. Wrap your component tree with <KernelProvider kernel={kernel}>."
+    );
+    this.name = "KernelProviderError";
+  }
+};
+function isSSR() {
+  return typeof window === "undefined";
+}
+function useKernel() {
+  if (isSSR()) {
+    if (typeof console !== "undefined" && console.warn) {
+      console.warn(
+        "[QuarKernel] useKernel called during server-side rendering. Event listeners will not work during SSR. Consider using useEffect to register listeners on the client side only."
+      );
+    }
+  }
+  const kernel = react.useContext(KernelContext);
+  if (!kernel) {
+    throw new KernelProviderError();
+  }
+  return kernel;
+}
+function useOn(eventName, handler, options) {
+  const kernel = useKernel();
+  react.useEffect(() => {
+    const off = kernel.on(eventName, handler, options);
+    if (options?.signal) {
+      const abortHandler = () => {
+        off();
+      };
+      options.signal.addEventListener("abort", abortHandler, { once: true });
+      return () => {
+        off();
+        if (!options.signal.aborted) {
+          options.signal.removeEventListener("abort", abortHandler);
+        }
+      };
+    }
+    return off;
+  }, [kernel, eventName, handler, options]);
+}
+function useEventState(eventName, initialValue, selectorOrOptions) {
+  const kernel = useKernel();
+  const [state, setState] = react.useState(initialValue);
+  const { selector, options } = react.useMemo(() => {
+    if (typeof selectorOrOptions === "function") {
+      return { selector: selectorOrOptions, options: void 0 };
+    }
+    if (selectorOrOptions) {
+      const { selector: sel, ...opts } = selectorOrOptions;
+      return { selector: sel, options: Object.keys(opts).length > 0 ? opts : void 0 };
+    }
+    return { selector: void 0, options: void 0 };
+  }, [selectorOrOptions]);
+  const selectorFn = selector || ((event) => event.data);
+  react.useEffect(() => {
+    const off = kernel.on(
+      eventName,
+      (event) => {
+        setState(selectorFn(event));
+      },
+      options
+    );
+    if (options?.signal) {
+      const abortHandler = () => {
+        off();
+      };
+      options.signal.addEventListener("abort", abortHandler, { once: true });
+      return () => {
+        off();
+        if (!options.signal.aborted) {
+          options.signal.removeEventListener("abort", abortHandler);
+        }
+      };
+    }
+    return off;
+  }, [kernel, eventName, selector, options]);
+  return state;
+}
+
+// src/index.ts
+var VERSION = "2.1.0";
+
+exports.KernelProvider = KernelProvider;
+exports.KernelProviderError = KernelProviderError;
+exports.VERSION = VERSION;
+exports.useEventState = useEventState;
+exports.useKernel = useKernel;
+exports.useOn = useOn;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/KernelProvider.tsx","../src/useKernel.ts","../src/useOn.ts","../src/useEventState.ts","../src/index.ts"],"names":["createContext","useContext","useEffect","useState","useMemo"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * KernelProvider - React Context Provider for QuarKernel\n *\n * Provides kernel instance to child components via React Context.\n * Use useKernel() hook to access the kernel in components.\n */\n\nimport { createContext, type ReactNode } from 'react';\nimport type { Kernel, EventMap } from '@quazardous/quarkernel';\n\n/**\n * React Context for kernel instance\n * @internal\n */\nexport const KernelContext = createContext<Kernel<any> | null>(null);\n\n/**\n * Props for KernelProvider component\n */\nexport interface KernelProviderProps<Events extends EventMap = EventMap> {\n  /** Kernel instance to provide to children */\n  kernel: Kernel<Events>;\n\n  /** Child components that can access the kernel */\n  children: ReactNode;\n}\n\n/**\n * Provider component that makes kernel available to child components\n *\n * @example\n * ```tsx\n * const kernel = createKernel();\n *\n * function App() {\n *   return (\n *     <KernelProvider kernel={kernel}>\n *       <MyComponent />\n *     </KernelProvider>\n *   );\n * }\n * ```\n */\nexport function KernelProvider<Events extends EventMap = EventMap>({\n  kernel,\n  children,\n}: KernelProviderProps<Events>) {\n  return (\n    <KernelContext.Provider value={kernel}>\n      {children}\n    </KernelContext.Provider>\n  );\n}\n","/**\n * useKernel - React hook to access kernel from context\n *\n * Must be used inside a KernelProvider component.\n * Includes SSR safety checks.\n */\n\nimport { useContext } from 'react';\nimport type { Kernel, EventMap } from '@quazardous/quarkernel';\nimport { KernelContext } from './KernelProvider.js';\n\n/**\n * Error thrown when useKernel is called outside KernelProvider\n */\nexport class KernelProviderError extends Error {\n  constructor() {\n    super(\n      'useKernel must be used within a KernelProvider. ' +\n      'Wrap your component tree with <KernelProvider kernel={kernel}>.'\n    );\n    this.name = 'KernelProviderError';\n  }\n}\n\n/**\n * Check if code is running during server-side rendering\n * @internal\n */\nfunction isSSR(): boolean {\n  return typeof window === 'undefined';\n}\n\n/**\n * React hook to access the kernel instance from context\n *\n * @throws {KernelProviderError} If called outside KernelProvider\n * @returns The kernel instance\n *\n * @example\n * ```tsx\n * function MyComponent() {\n *   const kernel = useKernel();\n *\n *   useEffect(() => {\n *     return kernel.on('user:login', (event) => {\n *       console.log('User logged in:', event.data);\n *     });\n *   }, [kernel]);\n *\n *   return <div>...</div>;\n * }\n * ```\n */\nexport function useKernel<Events extends EventMap = EventMap>(): Kernel<Events> {\n  if (isSSR()) {\n    if (typeof console !== 'undefined' && console.warn) {\n      console.warn(\n        '[QuarKernel] useKernel called during server-side rendering. ' +\n        'Event listeners will not work during SSR. ' +\n        'Consider using useEffect to register listeners on the client side only.'\n      );\n    }\n  }\n\n  const kernel = useContext(KernelContext);\n\n  if (!kernel) {\n    throw new KernelProviderError();\n  }\n\n  return kernel as Kernel<Events>;\n}\n","/**\n * useOn - React hook for event listeners with automatic cleanup\n *\n * Registers an event listener on the kernel and automatically removes it\n * when the component unmounts or dependencies change.\n */\n\nimport { useEffect } from 'react';\nimport type { EventMap, ListenerFunction, ListenerOptions } from '@quazardous/quarkernel';\nimport { useKernel } from './useKernel.js';\n\n/**\n * Hook to register an event listener with automatic cleanup\n *\n * The listener is registered when the component mounts and automatically\n * removed when the component unmounts or when dependencies change.\n *\n * @param eventName - Event name to listen to\n * @param handler - Listener function to execute when event fires\n * @param options - Optional listener options (priority, after, signal, etc.)\n *\n * @example\n * ```tsx\n * function UserStatus() {\n *   useOn('user:login', (event, context) => {\n *     console.log('User logged in:', event.data.userId);\n *   });\n *\n *   return <div>User Status</div>;\n * }\n * ```\n *\n * @example With options\n * ```tsx\n * function PriorityListener() {\n *   useOn('app:init', handler, {\n *     priority: 10,\n *     after: 'core-init'\n *   });\n *\n *   return <div>App</div>;\n * }\n * ```\n *\n * @example With AbortSignal\n * ```tsx\n * function ConditionalListener() {\n *   const [enabled, setEnabled] = useState(true);\n *   const controller = useMemo(() => new AbortController(), []);\n *\n *   useOn('data:update', handler, {\n *     signal: controller.signal\n *   });\n *\n *   const disable = () => controller.abort();\n *\n *   return <button onClick={disable}>Disable</button>;\n * }\n * ```\n */\nexport function useOn<Events extends EventMap = EventMap, K extends keyof Events = keyof Events>(\n  eventName: K,\n  handler: ListenerFunction<Events[K]>,\n  options?: ListenerOptions\n): void {\n  const kernel = useKernel<Events>();\n\n  useEffect(() => {\n    // Register listener and get cleanup function\n    const off = kernel.on(eventName, handler, options);\n\n    // If AbortSignal provided, also listen for abort\n    if (options?.signal) {\n      const abortHandler = () => {\n        off();\n      };\n\n      options.signal.addEventListener('abort', abortHandler, { once: true });\n\n      // Return cleanup that removes both listener and abort handler\n      return () => {\n        off();\n        if (!options.signal!.aborted) {\n          options.signal!.removeEventListener('abort', abortHandler);\n        }\n      };\n    }\n\n    // Return cleanup function\n    return off;\n  }, [kernel, eventName, handler, options]);\n}\n","/**\n * useEventState - React hook that maintains state synchronized with events\n *\n * Creates a state value that updates whenever a specific event is emitted.\n * Automatically cleans up the listener when the component unmounts.\n */\n\nimport { useState, useEffect, useMemo } from 'react';\nimport type { EventMap, ListenerOptions, IKernelEvent } from '@quazardous/quarkernel';\nimport { useKernel } from './useKernel.js';\n\n/**\n * Selector function to extract value from event\n */\nexport type EventStateSelector<T = any> = (event: IKernelEvent) => T;\n\n/**\n * Options for useEventState hook\n */\nexport interface UseEventStateOptions<T = any> extends ListenerOptions {\n  /**\n   * Selector function to extract value from event\n   * Default: (event) => event.data\n   */\n  selector?: EventStateSelector<T>;\n}\n\n/**\n * Hook to maintain state that updates on events\n *\n * The state value is updated whenever the specified event fires.\n * The listener is automatically cleaned up when the component unmounts.\n *\n * @param eventName - Event name to listen to\n * @param initialValue - Initial state value\n * @param selectorOrOptions - Optional selector function or options object\n * @returns Current state value\n *\n * @example\n * ```tsx\n * function UserInfo() {\n *   const user = useEventState<Events, 'user:login'>(\n *     'user:login',\n *     null\n *   );\n *\n *   return <div>User: {user?.userId}</div>;\n * }\n * ```\n *\n * @example With selector function\n * ```tsx\n * function Counter() {\n *   const count = useEventState('counter:updated', 0, (event) => event.data.value);\n *\n *   return <div>Count: {count}</div>;\n * }\n * ```\n *\n * @example With options object\n * ```tsx\n * function UserName() {\n *   const name = useEventState('user:login', 'Guest', {\n *     selector: (event) => event.data.name,\n *     priority: 10\n *   });\n *\n *   return <div>Hello, {name}</div>;\n * }\n * ```\n *\n * @example With AbortSignal\n * ```tsx\n * function ConditionalState() {\n *   const controller = useMemo(() => new AbortController(), []);\n *   const value = useEventState('data:update', null, {\n *     signal: controller.signal\n *   });\n *\n *   const stop = () => controller.abort();\n *\n *   return (\n *     <div>\n *       Value: {value}\n *       <button onClick={stop}>Stop Updates</button>\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useEventState<\n  Events extends EventMap = EventMap,\n  K extends keyof Events = keyof Events,\n  T = Events[K]\n>(\n  eventName: K,\n  initialValue: T,\n  selectorOrOptions?: EventStateSelector<T> | UseEventStateOptions<T>\n): T {\n  const kernel = useKernel<Events>();\n  const [state, setState] = useState<T>(initialValue);\n\n  // Normalize options: function becomes selector, object used as-is\n  const { selector, options } = useMemo(() => {\n    if (typeof selectorOrOptions === 'function') {\n      return { selector: selectorOrOptions, options: undefined };\n    }\n    if (selectorOrOptions) {\n      const { selector: sel, ...opts } = selectorOrOptions;\n      return { selector: sel, options: Object.keys(opts).length > 0 ? opts : undefined };\n    }\n    return { selector: undefined, options: undefined };\n  }, [selectorOrOptions]);\n\n  // Default selector returns event.data\n  const selectorFn = selector || ((event: IKernelEvent) => event.data as T);\n\n  useEffect(() => {\n    // Register listener that updates state\n    const off = kernel.on(\n      eventName,\n      (event: IKernelEvent<Events[K]>) => {\n        setState(selectorFn(event));\n      },\n      options\n    );\n\n    // If AbortSignal provided, also listen for abort\n    if (options?.signal) {\n      const abortHandler = () => {\n        off();\n      };\n\n      options.signal.addEventListener('abort', abortHandler, { once: true });\n\n      // Return cleanup that removes both listener and abort handler\n      return () => {\n        off();\n        if (!options.signal!.aborted) {\n          options.signal!.removeEventListener('abort', abortHandler);\n        }\n      };\n    }\n\n    // Return cleanup function\n    return off;\n  }, [kernel, eventName, selector, options]);\n\n  return state;\n}\n","/**\n * @quazardous/quarkernel-react - React bindings for QuarKernel\n *\n * Provides Context provider and hooks for using QuarKernel in React applications.\n *\n * @example\n * ```tsx\n * import { createKernel } from '@quazardous/quarkernel';\n * import { KernelProvider, useKernel } from '@quazardous/quarkernel-react';\n *\n * const kernel = createKernel();\n *\n * function App() {\n *   return (\n *     <KernelProvider kernel={kernel}>\n *       <MyComponent />\n *     </KernelProvider>\n *   );\n * }\n *\n * function MyComponent() {\n *   const kernel = useKernel();\n *\n *   useEffect(() => {\n *     return kernel.on('event', (event) => {\n *       console.log(event.data);\n *     });\n *   }, [kernel]);\n *\n *   return <div>...</div>;\n * }\n * ```\n */\n\nexport const VERSION = '2.1.0';\n\n// Components\nexport { KernelProvider, type KernelProviderProps } from './KernelProvider.js';\n\n// Hooks\nexport { useKernel, KernelProviderError } from './useKernel.js';\nexport { useOn } from './useOn.js';\nexport { useEventState, type EventStateSelector, type UseEventStateOptions } from './useEventState.js';\n"]}

package/dist/index.d.cts

@@ -0,0 +1,247 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { EventMap, Kernel, ListenerFunction, ListenerOptions, IKernelEvent } from '@quazardous/quarkernel';
+
+/**
+ * Props for KernelProvider component
+ */
+interface KernelProviderProps<Events extends EventMap = EventMap> {
+    /** Kernel instance to provide to children */
+    kernel: Kernel<Events>;
+    /** Child components that can access the kernel */
+    children: ReactNode;
+}
+/**
+ * Provider component that makes kernel available to child components
+ *
+ * @example
+ * ```tsx
+ * const kernel = createKernel();
+ *
+ * function App() {
+ *   return (
+ *     <KernelProvider kernel={kernel}>
+ *       <MyComponent />
+ *     </KernelProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function KernelProvider<Events extends EventMap = EventMap>({ kernel, children, }: KernelProviderProps<Events>): react_jsx_runtime.JSX.Element;
+
+/**
+ * useKernel - React hook to access kernel from context
+ *
+ * Must be used inside a KernelProvider component.
+ * Includes SSR safety checks.
+ */
+
+/**
+ * Error thrown when useKernel is called outside KernelProvider
+ */
+declare class KernelProviderError extends Error {
+    constructor();
+}
+/**
+ * React hook to access the kernel instance from context
+ *
+ * @throws {KernelProviderError} If called outside KernelProvider
+ * @returns The kernel instance
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const kernel = useKernel();
+ *
+ *   useEffect(() => {
+ *     return kernel.on('user:login', (event) => {
+ *       console.log('User logged in:', event.data);
+ *     });
+ *   }, [kernel]);
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+declare function useKernel<Events extends EventMap = EventMap>(): Kernel<Events>;
+
+/**
+ * useOn - React hook for event listeners with automatic cleanup
+ *
+ * Registers an event listener on the kernel and automatically removes it
+ * when the component unmounts or dependencies change.
+ */
+
+/**
+ * Hook to register an event listener with automatic cleanup
+ *
+ * The listener is registered when the component mounts and automatically
+ * removed when the component unmounts or when dependencies change.
+ *
+ * @param eventName - Event name to listen to
+ * @param handler - Listener function to execute when event fires
+ * @param options - Optional listener options (priority, after, signal, etc.)
+ *
+ * @example
+ * ```tsx
+ * function UserStatus() {
+ *   useOn('user:login', (event, context) => {
+ *     console.log('User logged in:', event.data.userId);
+ *   });
+ *
+ *   return <div>User Status</div>;
+ * }
+ * ```
+ *
+ * @example With options
+ * ```tsx
+ * function PriorityListener() {
+ *   useOn('app:init', handler, {
+ *     priority: 10,
+ *     after: 'core-init'
+ *   });
+ *
+ *   return <div>App</div>;
+ * }
+ * ```
+ *
+ * @example With AbortSignal
+ * ```tsx
+ * function ConditionalListener() {
+ *   const [enabled, setEnabled] = useState(true);
+ *   const controller = useMemo(() => new AbortController(), []);
+ *
+ *   useOn('data:update', handler, {
+ *     signal: controller.signal
+ *   });
+ *
+ *   const disable = () => controller.abort();
+ *
+ *   return <button onClick={disable}>Disable</button>;
+ * }
+ * ```
+ */
+declare function useOn<Events extends EventMap = EventMap, K extends keyof Events = keyof Events>(eventName: K, handler: ListenerFunction<Events[K]>, options?: ListenerOptions): void;
+
+/**
+ * useEventState - React hook that maintains state synchronized with events
+ *
+ * Creates a state value that updates whenever a specific event is emitted.
+ * Automatically cleans up the listener when the component unmounts.
+ */
+
+/**
+ * Selector function to extract value from event
+ */
+type EventStateSelector<T = any> = (event: IKernelEvent) => T;
+/**
+ * Options for useEventState hook
+ */
+interface UseEventStateOptions<T = any> extends ListenerOptions {
+    /**
+     * Selector function to extract value from event
+     * Default: (event) => event.data
+     */
+    selector?: EventStateSelector<T>;
+}
+/**
+ * Hook to maintain state that updates on events
+ *
+ * The state value is updated whenever the specified event fires.
+ * The listener is automatically cleaned up when the component unmounts.
+ *
+ * @param eventName - Event name to listen to
+ * @param initialValue - Initial state value
+ * @param selectorOrOptions - Optional selector function or options object
+ * @returns Current state value
+ *
+ * @example
+ * ```tsx
+ * function UserInfo() {
+ *   const user = useEventState<Events, 'user:login'>(
+ *     'user:login',
+ *     null
+ *   );
+ *
+ *   return <div>User: {user?.userId}</div>;
+ * }
+ * ```
+ *
+ * @example With selector function
+ * ```tsx
+ * function Counter() {
+ *   const count = useEventState('counter:updated', 0, (event) => event.data.value);
+ *
+ *   return <div>Count: {count}</div>;
+ * }
+ * ```
+ *
+ * @example With options object
+ * ```tsx
+ * function UserName() {
+ *   const name = useEventState('user:login', 'Guest', {
+ *     selector: (event) => event.data.name,
+ *     priority: 10
+ *   });
+ *
+ *   return <div>Hello, {name}</div>;
+ * }
+ * ```
+ *
+ * @example With AbortSignal
+ * ```tsx
+ * function ConditionalState() {
+ *   const controller = useMemo(() => new AbortController(), []);
+ *   const value = useEventState('data:update', null, {
+ *     signal: controller.signal
+ *   });
+ *
+ *   const stop = () => controller.abort();
+ *
+ *   return (
+ *     <div>
+ *       Value: {value}
+ *       <button onClick={stop}>Stop Updates</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useEventState<Events extends EventMap = EventMap, K extends keyof Events = keyof Events, T = Events[K]>(eventName: K, initialValue: T, selectorOrOptions?: EventStateSelector<T> | UseEventStateOptions<T>): T;
+
+/**
+ * @quazardous/quarkernel-react - React bindings for QuarKernel
+ *
+ * Provides Context provider and hooks for using QuarKernel in React applications.
+ *
+ * @example
+ * ```tsx
+ * import { createKernel } from '@quazardous/quarkernel';
+ * import { KernelProvider, useKernel } from '@quazardous/quarkernel-react';
+ *
+ * const kernel = createKernel();
+ *
+ * function App() {
+ *   return (
+ *     <KernelProvider kernel={kernel}>
+ *       <MyComponent />
+ *     </KernelProvider>
+ *   );
+ * }
+ *
+ * function MyComponent() {
+ *   const kernel = useKernel();
+ *
+ *   useEffect(() => {
+ *     return kernel.on('event', (event) => {
+ *       console.log(event.data);
+ *     });
+ *   }, [kernel]);
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+declare const VERSION = "2.1.0";
+
+export { type EventStateSelector, KernelProvider, KernelProviderError, type KernelProviderProps, type UseEventStateOptions, VERSION, useEventState, useKernel, useOn };

package/dist/index.d.ts

@@ -0,0 +1,247 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { EventMap, Kernel, ListenerFunction, ListenerOptions, IKernelEvent } from '@quazardous/quarkernel';
+
+/**
+ * Props for KernelProvider component
+ */
+interface KernelProviderProps<Events extends EventMap = EventMap> {
+    /** Kernel instance to provide to children */
+    kernel: Kernel<Events>;
+    /** Child components that can access the kernel */
+    children: ReactNode;
+}
+/**
+ * Provider component that makes kernel available to child components
+ *
+ * @example
+ * ```tsx
+ * const kernel = createKernel();
+ *
+ * function App() {
+ *   return (
+ *     <KernelProvider kernel={kernel}>
+ *       <MyComponent />
+ *     </KernelProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function KernelProvider<Events extends EventMap = EventMap>({ kernel, children, }: KernelProviderProps<Events>): react_jsx_runtime.JSX.Element;
+
+/**
+ * useKernel - React hook to access kernel from context
+ *
+ * Must be used inside a KernelProvider component.
+ * Includes SSR safety checks.
+ */
+
+/**
+ * Error thrown when useKernel is called outside KernelProvider
+ */
+declare class KernelProviderError extends Error {
+    constructor();
+}
+/**
+ * React hook to access the kernel instance from context
+ *
+ * @throws {KernelProviderError} If called outside KernelProvider
+ * @returns The kernel instance
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const kernel = useKernel();
+ *
+ *   useEffect(() => {
+ *     return kernel.on('user:login', (event) => {
+ *       console.log('User logged in:', event.data);
+ *     });
+ *   }, [kernel]);
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+declare function useKernel<Events extends EventMap = EventMap>(): Kernel<Events>;
+
+/**
+ * useOn - React hook for event listeners with automatic cleanup
+ *
+ * Registers an event listener on the kernel and automatically removes it
+ * when the component unmounts or dependencies change.
+ */
+
+/**
+ * Hook to register an event listener with automatic cleanup
+ *
+ * The listener is registered when the component mounts and automatically
+ * removed when the component unmounts or when dependencies change.
+ *
+ * @param eventName - Event name to listen to
+ * @param handler - Listener function to execute when event fires
+ * @param options - Optional listener options (priority, after, signal, etc.)
+ *
+ * @example
+ * ```tsx
+ * function UserStatus() {
+ *   useOn('user:login', (event, context) => {
+ *     console.log('User logged in:', event.data.userId);
+ *   });
+ *
+ *   return <div>User Status</div>;
+ * }
+ * ```
+ *
+ * @example With options
+ * ```tsx
+ * function PriorityListener() {
+ *   useOn('app:init', handler, {
+ *     priority: 10,
+ *     after: 'core-init'
+ *   });
+ *
+ *   return <div>App</div>;
+ * }
+ * ```
+ *
+ * @example With AbortSignal
+ * ```tsx
+ * function ConditionalListener() {
+ *   const [enabled, setEnabled] = useState(true);
+ *   const controller = useMemo(() => new AbortController(), []);
+ *
+ *   useOn('data:update', handler, {
+ *     signal: controller.signal
+ *   });
+ *
+ *   const disable = () => controller.abort();
+ *
+ *   return <button onClick={disable}>Disable</button>;
+ * }
+ * ```
+ */
+declare function useOn<Events extends EventMap = EventMap, K extends keyof Events = keyof Events>(eventName: K, handler: ListenerFunction<Events[K]>, options?: ListenerOptions): void;
+
+/**
+ * useEventState - React hook that maintains state synchronized with events
+ *
+ * Creates a state value that updates whenever a specific event is emitted.
+ * Automatically cleans up the listener when the component unmounts.
+ */
+
+/**
+ * Selector function to extract value from event
+ */
+type EventStateSelector<T = any> = (event: IKernelEvent) => T;
+/**
+ * Options for useEventState hook
+ */
+interface UseEventStateOptions<T = any> extends ListenerOptions {
+    /**
+     * Selector function to extract value from event
+     * Default: (event) => event.data
+     */
+    selector?: EventStateSelector<T>;
+}
+/**
+ * Hook to maintain state that updates on events
+ *
+ * The state value is updated whenever the specified event fires.
+ * The listener is automatically cleaned up when the component unmounts.
+ *
+ * @param eventName - Event name to listen to
+ * @param initialValue - Initial state value
+ * @param selectorOrOptions - Optional selector function or options object
+ * @returns Current state value
+ *
+ * @example
+ * ```tsx
+ * function UserInfo() {
+ *   const user = useEventState<Events, 'user:login'>(
+ *     'user:login',
+ *     null
+ *   );
+ *
+ *   return <div>User: {user?.userId}</div>;
+ * }
+ * ```
+ *
+ * @example With selector function
+ * ```tsx
+ * function Counter() {
+ *   const count = useEventState('counter:updated', 0, (event) => event.data.value);
+ *
+ *   return <div>Count: {count}</div>;
+ * }
+ * ```
+ *
+ * @example With options object
+ * ```tsx
+ * function UserName() {
+ *   const name = useEventState('user:login', 'Guest', {
+ *     selector: (event) => event.data.name,
+ *     priority: 10
+ *   });
+ *
+ *   return <div>Hello, {name}</div>;
+ * }
+ * ```
+ *
+ * @example With AbortSignal
+ * ```tsx
+ * function ConditionalState() {
+ *   const controller = useMemo(() => new AbortController(), []);
+ *   const value = useEventState('data:update', null, {
+ *     signal: controller.signal
+ *   });
+ *
+ *   const stop = () => controller.abort();
+ *
+ *   return (
+ *     <div>
+ *       Value: {value}
+ *       <button onClick={stop}>Stop Updates</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useEventState<Events extends EventMap = EventMap, K extends keyof Events = keyof Events, T = Events[K]>(eventName: K, initialValue: T, selectorOrOptions?: EventStateSelector<T> | UseEventStateOptions<T>): T;
+
+/**
+ * @quazardous/quarkernel-react - React bindings for QuarKernel
+ *
+ * Provides Context provider and hooks for using QuarKernel in React applications.
+ *
+ * @example
+ * ```tsx
+ * import { createKernel } from '@quazardous/quarkernel';
+ * import { KernelProvider, useKernel } from '@quazardous/quarkernel-react';
+ *
+ * const kernel = createKernel();
+ *
+ * function App() {
+ *   return (
+ *     <KernelProvider kernel={kernel}>
+ *       <MyComponent />
+ *     </KernelProvider>
+ *   );
+ * }
+ *
+ * function MyComponent() {
+ *   const kernel = useKernel();
+ *
+ *   useEffect(() => {
+ *     return kernel.on('event', (event) => {
+ *       console.log(event.data);
+ *     });
+ *   }, [kernel]);
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+declare const VERSION = "2.1.0";
+
+export { type EventStateSelector, KernelProvider, KernelProviderError, type KernelProviderProps, type UseEventStateOptions, VERSION, useEventState, useKernel, useOn };

package/dist/index.js

@@ -0,0 +1,100 @@
+import { createContext, useContext, useEffect, useState, useMemo } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+// src/KernelProvider.tsx
+var KernelContext = createContext(null);
+function KernelProvider({
+  kernel,
+  children
+}) {
+  return /* @__PURE__ */ jsx(KernelContext.Provider, { value: kernel, children });
+}
+var KernelProviderError = class extends Error {
+  constructor() {
+    super(
+      "useKernel must be used within a KernelProvider. Wrap your component tree with <KernelProvider kernel={kernel}>."
+    );
+    this.name = "KernelProviderError";
+  }
+};
+function isSSR() {
+  return typeof window === "undefined";
+}
+function useKernel() {
+  if (isSSR()) {
+    if (typeof console !== "undefined" && console.warn) {
+      console.warn(
+        "[QuarKernel] useKernel called during server-side rendering. Event listeners will not work during SSR. Consider using useEffect to register listeners on the client side only."
+      );
+    }
+  }
+  const kernel = useContext(KernelContext);
+  if (!kernel) {
+    throw new KernelProviderError();
+  }
+  return kernel;
+}
+function useOn(eventName, handler, options) {
+  const kernel = useKernel();
+  useEffect(() => {
+    const off = kernel.on(eventName, handler, options);
+    if (options?.signal) {
+      const abortHandler = () => {
+        off();
+      };
+      options.signal.addEventListener("abort", abortHandler, { once: true });
+      return () => {
+        off();
+        if (!options.signal.aborted) {
+          options.signal.removeEventListener("abort", abortHandler);
+        }
+      };
+    }
+    return off;
+  }, [kernel, eventName, handler, options]);
+}
+function useEventState(eventName, initialValue, selectorOrOptions) {
+  const kernel = useKernel();
+  const [state, setState] = useState(initialValue);
+  const { selector, options } = useMemo(() => {
+    if (typeof selectorOrOptions === "function") {
+      return { selector: selectorOrOptions, options: void 0 };
+    }
+    if (selectorOrOptions) {
+      const { selector: sel, ...opts } = selectorOrOptions;
+      return { selector: sel, options: Object.keys(opts).length > 0 ? opts : void 0 };
+    }
+    return { selector: void 0, options: void 0 };
+  }, [selectorOrOptions]);
+  const selectorFn = selector || ((event) => event.data);
+  useEffect(() => {
+    const off = kernel.on(
+      eventName,
+      (event) => {
+        setState(selectorFn(event));
+      },
+      options
+    );
+    if (options?.signal) {
+      const abortHandler = () => {
+        off();
+      };
+      options.signal.addEventListener("abort", abortHandler, { once: true });
+      return () => {
+        off();
+        if (!options.signal.aborted) {
+          options.signal.removeEventListener("abort", abortHandler);
+        }
+      };
+    }
+    return off;
+  }, [kernel, eventName, selector, options]);
+  return state;
+}
+
+// src/index.ts
+var VERSION = "2.1.0";
+
+export { KernelProvider, KernelProviderError, VERSION, useEventState, useKernel, useOn };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/KernelProvider.tsx","../src/useKernel.ts","../src/useOn.ts","../src/useEventState.ts","../src/index.ts"],"names":["useEffect"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * KernelProvider - React Context Provider for QuarKernel\n *\n * Provides kernel instance to child components via React Context.\n * Use useKernel() hook to access the kernel in components.\n */\n\nimport { createContext, type ReactNode } from 'react';\nimport type { Kernel, EventMap } from '@quazardous/quarkernel';\n\n/**\n * React Context for kernel instance\n * @internal\n */\nexport const KernelContext = createContext<Kernel<any> | null>(null);\n\n/**\n * Props for KernelProvider component\n */\nexport interface KernelProviderProps<Events extends EventMap = EventMap> {\n  /** Kernel instance to provide to children */\n  kernel: Kernel<Events>;\n\n  /** Child components that can access the kernel */\n  children: ReactNode;\n}\n\n/**\n * Provider component that makes kernel available to child components\n *\n * @example\n * ```tsx\n * const kernel = createKernel();\n *\n * function App() {\n *   return (\n *     <KernelProvider kernel={kernel}>\n *       <MyComponent />\n *     </KernelProvider>\n *   );\n * }\n * ```\n */\nexport function KernelProvider<Events extends EventMap = EventMap>({\n  kernel,\n  children,\n}: KernelProviderProps<Events>) {\n  return (\n    <KernelContext.Provider value={kernel}>\n      {children}\n    </KernelContext.Provider>\n  );\n}\n","/**\n * useKernel - React hook to access kernel from context\n *\n * Must be used inside a KernelProvider component.\n * Includes SSR safety checks.\n */\n\nimport { useContext } from 'react';\nimport type { Kernel, EventMap } from '@quazardous/quarkernel';\nimport { KernelContext } from './KernelProvider.js';\n\n/**\n * Error thrown when useKernel is called outside KernelProvider\n */\nexport class KernelProviderError extends Error {\n  constructor() {\n    super(\n      'useKernel must be used within a KernelProvider. ' +\n      'Wrap your component tree with <KernelProvider kernel={kernel}>.'\n    );\n    this.name = 'KernelProviderError';\n  }\n}\n\n/**\n * Check if code is running during server-side rendering\n * @internal\n */\nfunction isSSR(): boolean {\n  return typeof window === 'undefined';\n}\n\n/**\n * React hook to access the kernel instance from context\n *\n * @throws {KernelProviderError} If called outside KernelProvider\n * @returns The kernel instance\n *\n * @example\n * ```tsx\n * function MyComponent() {\n *   const kernel = useKernel();\n *\n *   useEffect(() => {\n *     return kernel.on('user:login', (event) => {\n *       console.log('User logged in:', event.data);\n *     });\n *   }, [kernel]);\n *\n *   return <div>...</div>;\n * }\n * ```\n */\nexport function useKernel<Events extends EventMap = EventMap>(): Kernel<Events> {\n  if (isSSR()) {\n    if (typeof console !== 'undefined' && console.warn) {\n      console.warn(\n        '[QuarKernel] useKernel called during server-side rendering. ' +\n        'Event listeners will not work during SSR. ' +\n        'Consider using useEffect to register listeners on the client side only.'\n      );\n    }\n  }\n\n  const kernel = useContext(KernelContext);\n\n  if (!kernel) {\n    throw new KernelProviderError();\n  }\n\n  return kernel as Kernel<Events>;\n}\n","/**\n * useOn - React hook for event listeners with automatic cleanup\n *\n * Registers an event listener on the kernel and automatically removes it\n * when the component unmounts or dependencies change.\n */\n\nimport { useEffect } from 'react';\nimport type { EventMap, ListenerFunction, ListenerOptions } from '@quazardous/quarkernel';\nimport { useKernel } from './useKernel.js';\n\n/**\n * Hook to register an event listener with automatic cleanup\n *\n * The listener is registered when the component mounts and automatically\n * removed when the component unmounts or when dependencies change.\n *\n * @param eventName - Event name to listen to\n * @param handler - Listener function to execute when event fires\n * @param options - Optional listener options (priority, after, signal, etc.)\n *\n * @example\n * ```tsx\n * function UserStatus() {\n *   useOn('user:login', (event, context) => {\n *     console.log('User logged in:', event.data.userId);\n *   });\n *\n *   return <div>User Status</div>;\n * }\n * ```\n *\n * @example With options\n * ```tsx\n * function PriorityListener() {\n *   useOn('app:init', handler, {\n *     priority: 10,\n *     after: 'core-init'\n *   });\n *\n *   return <div>App</div>;\n * }\n * ```\n *\n * @example With AbortSignal\n * ```tsx\n * function ConditionalListener() {\n *   const [enabled, setEnabled] = useState(true);\n *   const controller = useMemo(() => new AbortController(), []);\n *\n *   useOn('data:update', handler, {\n *     signal: controller.signal\n *   });\n *\n *   const disable = () => controller.abort();\n *\n *   return <button onClick={disable}>Disable</button>;\n * }\n * ```\n */\nexport function useOn<Events extends EventMap = EventMap, K extends keyof Events = keyof Events>(\n  eventName: K,\n  handler: ListenerFunction<Events[K]>,\n  options?: ListenerOptions\n): void {\n  const kernel = useKernel<Events>();\n\n  useEffect(() => {\n    // Register listener and get cleanup function\n    const off = kernel.on(eventName, handler, options);\n\n    // If AbortSignal provided, also listen for abort\n    if (options?.signal) {\n      const abortHandler = () => {\n        off();\n      };\n\n      options.signal.addEventListener('abort', abortHandler, { once: true });\n\n      // Return cleanup that removes both listener and abort handler\n      return () => {\n        off();\n        if (!options.signal!.aborted) {\n          options.signal!.removeEventListener('abort', abortHandler);\n        }\n      };\n    }\n\n    // Return cleanup function\n    return off;\n  }, [kernel, eventName, handler, options]);\n}\n","/**\n * useEventState - React hook that maintains state synchronized with events\n *\n * Creates a state value that updates whenever a specific event is emitted.\n * Automatically cleans up the listener when the component unmounts.\n */\n\nimport { useState, useEffect, useMemo } from 'react';\nimport type { EventMap, ListenerOptions, IKernelEvent } from '@quazardous/quarkernel';\nimport { useKernel } from './useKernel.js';\n\n/**\n * Selector function to extract value from event\n */\nexport type EventStateSelector<T = any> = (event: IKernelEvent) => T;\n\n/**\n * Options for useEventState hook\n */\nexport interface UseEventStateOptions<T = any> extends ListenerOptions {\n  /**\n   * Selector function to extract value from event\n   * Default: (event) => event.data\n   */\n  selector?: EventStateSelector<T>;\n}\n\n/**\n * Hook to maintain state that updates on events\n *\n * The state value is updated whenever the specified event fires.\n * The listener is automatically cleaned up when the component unmounts.\n *\n * @param eventName - Event name to listen to\n * @param initialValue - Initial state value\n * @param selectorOrOptions - Optional selector function or options object\n * @returns Current state value\n *\n * @example\n * ```tsx\n * function UserInfo() {\n *   const user = useEventState<Events, 'user:login'>(\n *     'user:login',\n *     null\n *   );\n *\n *   return <div>User: {user?.userId}</div>;\n * }\n * ```\n *\n * @example With selector function\n * ```tsx\n * function Counter() {\n *   const count = useEventState('counter:updated', 0, (event) => event.data.value);\n *\n *   return <div>Count: {count}</div>;\n * }\n * ```\n *\n * @example With options object\n * ```tsx\n * function UserName() {\n *   const name = useEventState('user:login', 'Guest', {\n *     selector: (event) => event.data.name,\n *     priority: 10\n *   });\n *\n *   return <div>Hello, {name}</div>;\n * }\n * ```\n *\n * @example With AbortSignal\n * ```tsx\n * function ConditionalState() {\n *   const controller = useMemo(() => new AbortController(), []);\n *   const value = useEventState('data:update', null, {\n *     signal: controller.signal\n *   });\n *\n *   const stop = () => controller.abort();\n *\n *   return (\n *     <div>\n *       Value: {value}\n *       <button onClick={stop}>Stop Updates</button>\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useEventState<\n  Events extends EventMap = EventMap,\n  K extends keyof Events = keyof Events,\n  T = Events[K]\n>(\n  eventName: K,\n  initialValue: T,\n  selectorOrOptions?: EventStateSelector<T> | UseEventStateOptions<T>\n): T {\n  const kernel = useKernel<Events>();\n  const [state, setState] = useState<T>(initialValue);\n\n  // Normalize options: function becomes selector, object used as-is\n  const { selector, options } = useMemo(() => {\n    if (typeof selectorOrOptions === 'function') {\n      return { selector: selectorOrOptions, options: undefined };\n    }\n    if (selectorOrOptions) {\n      const { selector: sel, ...opts } = selectorOrOptions;\n      return { selector: sel, options: Object.keys(opts).length > 0 ? opts : undefined };\n    }\n    return { selector: undefined, options: undefined };\n  }, [selectorOrOptions]);\n\n  // Default selector returns event.data\n  const selectorFn = selector || ((event: IKernelEvent) => event.data as T);\n\n  useEffect(() => {\n    // Register listener that updates state\n    const off = kernel.on(\n      eventName,\n      (event: IKernelEvent<Events[K]>) => {\n        setState(selectorFn(event));\n      },\n      options\n    );\n\n    // If AbortSignal provided, also listen for abort\n    if (options?.signal) {\n      const abortHandler = () => {\n        off();\n      };\n\n      options.signal.addEventListener('abort', abortHandler, { once: true });\n\n      // Return cleanup that removes both listener and abort handler\n      return () => {\n        off();\n        if (!options.signal!.aborted) {\n          options.signal!.removeEventListener('abort', abortHandler);\n        }\n      };\n    }\n\n    // Return cleanup function\n    return off;\n  }, [kernel, eventName, selector, options]);\n\n  return state;\n}\n","/**\n * @quazardous/quarkernel-react - React bindings for QuarKernel\n *\n * Provides Context provider and hooks for using QuarKernel in React applications.\n *\n * @example\n * ```tsx\n * import { createKernel } from '@quazardous/quarkernel';\n * import { KernelProvider, useKernel } from '@quazardous/quarkernel-react';\n *\n * const kernel = createKernel();\n *\n * function App() {\n *   return (\n *     <KernelProvider kernel={kernel}>\n *       <MyComponent />\n *     </KernelProvider>\n *   );\n * }\n *\n * function MyComponent() {\n *   const kernel = useKernel();\n *\n *   useEffect(() => {\n *     return kernel.on('event', (event) => {\n *       console.log(event.data);\n *     });\n *   }, [kernel]);\n *\n *   return <div>...</div>;\n * }\n * ```\n */\n\nexport const VERSION = '2.1.0';\n\n// Components\nexport { KernelProvider, type KernelProviderProps } from './KernelProvider.js';\n\n// Hooks\nexport { useKernel, KernelProviderError } from './useKernel.js';\nexport { useOn } from './useOn.js';\nexport { useEventState, type EventStateSelector, type UseEventStateOptions } from './useEventState.js';\n"]}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@quazardous/quarkernel-react",
+  "version": "2.1.0",
+  "type": "module",
+  "description": "React bindings for QuarKernel - Context provider and hooks",
+  "author": "quazardous <berliozdavid@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/quazardous/quarkernel.git",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/quazardous/quarkernel/issues"
+  },
+  "homepage": "https://github.com/quazardous/quarkernel#readme",
+  "keywords": [
+    "react",
+    "hooks",
+    "context",
+    "quarkernel",
+    "event",
+    "kernel"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "build:watch": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  },
+  "peerDependencies": {
+    "@quazardous/quarkernel": "^2.1.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@quazardous/quarkernel": "file:../quarkernel",
+    "@testing-library/react": "^14.0.0",
+    "@types/react": "^18.2.0",
+    "jsdom": "^23.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  }
+}