@quazardous/quarkernel-vue 2.1.0

package/README.md

@@ -0,0 +1,90 @@
+# @quazardous/quarkernel-vue
+
+Vue 3 adapter for QuarKernel - seamless event kernel integration with Vue's reactivity system.
+
+## Installation
+
+```bash
+npm install @quazardous/quarkernel @quazardous/quarkernel-vue
+# or
+pnpm add @quazardous/quarkernel @quazardous/quarkernel-vue
+```
+
+## Usage
+
+### 1. Install the Plugin
+
+```typescript
+import { createApp } from 'vue';
+import { createKernel } from '@quazardous/quarkernel';
+import { QuarKernelPlugin } from '@quazardous/quarkernel-vue';
+import App from './App.vue';
+
+const qk = createKernel();
+const app = createApp(App);
+
+app.use(QuarKernelPlugin, { kernel });
+app.mount('#app');
+```
+
+### 2. Use in Components
+
+```vue
+<script setup lang="ts">
+import { useKernel } from '@quazardous/quarkernel-vue';
+import { onMounted } from 'vue';
+
+const qk = useKernel();
+
+onMounted(() => {
+  qk.on('user:login', async (event) => {
+    console.log('User logged in:', event.data);
+  });
+});
+
+async function login() {
+  await qk.emit('user:login', { userId: '123' });
+}
+</script>
+```
+
+## API
+
+### QuarKernelPlugin
+
+Vue plugin that registers the kernel instance globally.
+
+**Options:**
+- `kernel`: Kernel instance to provide globally (required)
+
+### useKernel()
+
+Composable to access the kernel instance from within component setup functions.
+
+**Returns:** The kernel instance provided via the plugin
+
+**Throws:**
+- Error if called outside setup() context
+- Error if plugin not installed
+
+**SSR Warning:** Warns when accessed during server-side rendering
+
+## TypeScript Support
+
+Full TypeScript support with typed events:
+
+```typescript
+interface AppEvents {
+  'user:login': { userId: string };
+  'user:logout': { userId: string };
+}
+
+const qk = createKernel<AppEvents>();
+
+// In component
+const qk = useKernel<typeof kernel>();
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,68 @@
+'use strict';
+
+var vue = require('vue');
+
+// src/plugin.ts
+var KERNEL_INJECTION_KEY = /* @__PURE__ */ Symbol("quarkernel");
+var QuarKernelPlugin = {
+  install(app, options) {
+    if (!options || !options.kernel) {
+      throw new Error("[QuarKernel Vue] Plugin requires a kernel instance in options");
+    }
+    app.provide(KERNEL_INJECTION_KEY, options.kernel);
+  }
+};
+function isSSR() {
+  return typeof window === "undefined";
+}
+function useKernel() {
+  const instance = vue.getCurrentInstance();
+  if (!instance) {
+    throw new Error("[QuarKernel Vue] useKernel() must be called within setup() function");
+  }
+  if (isSSR()) {
+    console.warn(
+      "[QuarKernel Vue] useKernel() called during server-side rendering. Kernel events should typically run client-side only. Ensure you guard kernel usage in onMounted() or similar lifecycle hooks."
+    );
+  }
+  const kernel = vue.inject(KERNEL_INJECTION_KEY);
+  if (!kernel) {
+    throw new Error(
+      "[QuarKernel Vue] Kernel instance not found. Did you install QuarKernelPlugin with app.use(QuarKernelPlugin, { kernel })?"
+    );
+  }
+  return kernel;
+}
+function useOn(eventName, handler, options) {
+  const kernel = useKernel();
+  const unbind = kernel.on(eventName, handler, options);
+  vue.onUnmounted(() => {
+    unbind();
+  });
+  return unbind;
+}
+function useEventState(eventName, initialValue, options) {
+  const kernel = useKernel();
+  const state = vue.ref(initialValue);
+  const { transform, ...listenerOptions } = options || {};
+  const transformFn = transform || ((event) => event.data);
+  const unbind = kernel.on(
+    eventName,
+    (event) => {
+      state.value = transformFn(event);
+    },
+    listenerOptions
+  );
+  vue.onUnmounted(() => {
+    unbind();
+  });
+  return state;
+}
+
+exports.KERNEL_INJECTION_KEY = KERNEL_INJECTION_KEY;
+exports.QuarKernelPlugin = QuarKernelPlugin;
+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/plugin.ts","../src/use-kernel.ts","../src/use-on.ts","../src/use-event-state.ts"],"names":["getCurrentInstance","inject","onUnmounted","ref"],"mappings":";;;;;AAcO,IAAM,oBAAA,0BAA8B,YAAY;AA2BhD,IAAM,gBAAA,GAA2B;AAAA,EACtC,OAAA,CAAQ,KAAU,OAAA,EAAkC;AAClD,IAAA,IAAI,CAAC,OAAA,IAAW,CAAC,OAAA,CAAQ,MAAA,EAAQ;AAC/B,MAAA,MAAM,IAAI,MAAM,+DAA+D,CAAA;AAAA,IACjF;AAEA,IAAA,GAAA,CAAI,OAAA,CAAQ,oBAAA,EAAsB,OAAA,CAAQ,MAAM,CAAA;AAAA,EAClD;AACF;AClCA,SAAS,KAAA,GAAiB;AACxB,EAAA,OAAO,OAAO,MAAA,KAAW,WAAA;AAC3B;AA0BO,SAAS,SAAA,GAA0C;AAExD,EAAA,MAAM,WAAWA,sBAAA,EAAmB;AACpC,EAAA,IAAI,CAAC,QAAA,EAAU;AACb,IAAA,MAAM,IAAI,MAAM,qEAAqE,CAAA;AAAA,EACvF;AAGA,EAAA,IAAI,OAAM,EAAG;AACX,IAAA,OAAA,CAAQ,IAAA;AAAA,MACN;AAAA,KAGF;AAAA,EACF;AAGA,EAAA,MAAM,MAAA,GAASC,WAAU,oBAAoB,CAAA;AAE7C,EAAA,IAAI,CAAC,MAAA,EAAQ;AACX,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,KAEF;AAAA,EACF;AAEA,EAAA,OAAO,MAAA;AACT;ACpBO,SAAS,KAAA,CACd,SAAA,EACA,OAAA,EACA,OAAA,EACY;AACZ,EAAA,MAAM,SAAS,SAAA,EAAU;AAGzB,EAAA,MAAM,MAAA,GAAS,MAAA,CAAO,EAAA,CAAG,SAAA,EAAW,SAAS,OAAO,CAAA;AAGpD,EAAAC,eAAA,CAAY,MAAM;AAChB,IAAA,MAAA,EAAO;AAAA,EACT,CAAC,CAAA;AAGD,EAAA,OAAO,MAAA;AACT;ACAO,SAAS,aAAA,CACd,SAAA,EACA,YAAA,EACA,OAAA,EACQ;AACR,EAAA,MAAM,SAAS,SAAA,EAAU;AACzB,EAAA,MAAM,KAAA,GAAQC,QAAO,YAAY,CAAA;AAGjC,EAAA,MAAM,EAAE,SAAA,EAAW,GAAG,eAAA,EAAgB,GAAI,WAAW,EAAC;AACtD,EAAA,MAAM,WAAA,GAAc,SAAA,KAAc,CAAC,KAAA,KAAwB,KAAA,CAAM,IAAA,CAAA;AAGjE,EAAA,MAAM,SAAS,MAAA,CAAO,EAAA;AAAA,IACpB,SAAA;AAAA,IACA,CAAC,KAAA,KAAwB;AACvB,MAAA,KAAA,CAAM,KAAA,GAAQ,YAAY,KAAK,CAAA;AAAA,IACjC,CAAA;AAAA,IACA;AAAA,GACF;AAGA,EAAAD,gBAAY,MAAM;AAChB,IAAA,MAAA,EAAO;AAAA,EACT,CAAC,CAAA;AAED,EAAA,OAAO,KAAA;AACT","file":"index.cjs","sourcesContent":["/**\n * Vue plugin for QuarKernel integration\n *\n * Provides global kernel instance access via Vue's provide/inject system.\n * Use with app.use(QuarKernelPlugin, { kernel })\n */\n\nimport type { App, Plugin } from 'vue';\nimport type { Kernel } from '@quazardous/quarkernel';\n\n/**\n * Injection key for kernel instance\n * @internal\n */\nexport const KERNEL_INJECTION_KEY = Symbol('quarkernel');\n\n/**\n * Plugin options\n */\nexport interface QuarKernelPluginOptions {\n  /** Kernel instance to provide globally */\n  kernel: Kernel;\n}\n\n/**\n * QuarKernel Vue plugin\n *\n * Registers kernel instance globally for access via useKernel() composable\n *\n * @example\n * ```ts\n * import { createApp } from 'vue';\n * import { createKernel } from '@quazardous/quarkernel';\n * import { QuarKernelPlugin } from '@quazardous/quarkernel-vue';\n *\n * const kernel = createKernel();\n * const app = createApp(App);\n *\n * app.use(QuarKernelPlugin, { kernel });\n * ```\n */\nexport const QuarKernelPlugin: Plugin = {\n  install(app: App, options: QuarKernelPluginOptions) {\n    if (!options || !options.kernel) {\n      throw new Error('[QuarKernel Vue] Plugin requires a kernel instance in options');\n    }\n\n    app.provide(KERNEL_INJECTION_KEY, options.kernel);\n  },\n};\n","/**\n * Vue composable for accessing QuarKernel instance\n *\n * Provides type-safe access to the kernel instance registered via plugin.\n * Includes SSR guards to prevent server-side usage.\n */\n\nimport { inject, getCurrentInstance } from 'vue';\nimport type { Kernel } from '@quazardous/quarkernel';\nimport { KERNEL_INJECTION_KEY } from './plugin.js';\n\n/**\n * Check if running in SSR context\n * @internal\n */\nfunction isSSR(): boolean {\n  return typeof window === 'undefined';\n}\n\n/**\n * Composable to access QuarKernel instance from components\n *\n * Must be called within setup() function of a component where the plugin was installed.\n * Throws error if plugin not installed or called outside setup context.\n * Warns when accessed during SSR.\n *\n * @example\n * ```ts\n * import { useKernel } from '@quazardous/quarkernel-vue';\n *\n * export default {\n *   setup() {\n *     const kernel = useKernel();\n *\n *     kernel.on('user:login', async (event) => {\n *       console.log('User logged in:', event.data);\n *     });\n *\n *     return {};\n *   }\n * }\n * ```\n */\nexport function useKernel<T extends Kernel = Kernel>(): T {\n  // Check if called within Vue component setup\n  const instance = getCurrentInstance();\n  if (!instance) {\n    throw new Error('[QuarKernel Vue] useKernel() must be called within setup() function');\n  }\n\n  // SSR guard - warn but don't block (for flexibility)\n  if (isSSR()) {\n    console.warn(\n      '[QuarKernel Vue] useKernel() called during server-side rendering. ' +\n      'Kernel events should typically run client-side only. ' +\n      'Ensure you guard kernel usage in onMounted() or similar lifecycle hooks.'\n    );\n  }\n\n  // Inject kernel instance\n  const kernel = inject<T>(KERNEL_INJECTION_KEY);\n\n  if (!kernel) {\n    throw new Error(\n      '[QuarKernel Vue] Kernel instance not found. ' +\n      'Did you install QuarKernelPlugin with app.use(QuarKernelPlugin, { kernel })?'\n    );\n  }\n\n  return kernel;\n}\n","/**\n * Vue composable for event listener registration with automatic cleanup\n *\n * Automatically removes the listener when the component is unmounted.\n * Supports manual cleanup via AbortSignal.\n */\n\nimport { onUnmounted } from 'vue';\nimport type { ListenerFunction, ListenerOptions } from '@quazardous/quarkernel';\nimport { useKernel } from './use-kernel.js';\n\n/**\n * Composable to register event listeners with automatic cleanup\n *\n * The listener is automatically removed when the component unmounts via Vue's\n * onUnmounted lifecycle hook. Manual cleanup is also supported via AbortSignal.\n *\n * @template K - Event name type\n * @param eventName - Event name to listen for\n * @param handler - Listener function\n * @param options - Listener options (optional)\n * @returns Cleanup function to manually remove listener\n *\n * @example\n * ```ts\n * import { useOn } from '@quazardous/quarkernel-vue';\n *\n * export default {\n *   setup() {\n *     // Automatically cleaned up on unmount\n *     useOn('user:login', async (event) => {\n *       console.log('User logged in:', event.data);\n *     });\n *\n *     // With options\n *     useOn('data:update', handler, {\n *       priority: 10,\n *       id: 'my-listener'\n *     });\n *\n *     // Manual cleanup via AbortSignal\n *     const controller = new AbortController();\n *     useOn('events', handler, {\n *       signal: controller.signal\n *     });\n *     // Later: controller.abort();\n *   }\n * }\n * ```\n */\nexport function useOn<K extends string = string>(\n  eventName: K,\n  handler: ListenerFunction,\n  options?: ListenerOptions\n): () => void {\n  const kernel = useKernel();\n\n  // Register listener on kernel\n  const unbind = kernel.on(eventName, handler, options);\n\n  // Auto-cleanup on component unmount\n  onUnmounted(() => {\n    unbind();\n  });\n\n  // Return unbind for manual cleanup\n  return unbind;\n}\n","/**\n * Vue composable for reactive event state\n *\n * Maintains a reactive ref that updates whenever the specified event is emitted.\n * Automatically removes the listener when the component is unmounted.\n */\n\nimport { ref, onUnmounted } from 'vue';\nimport type { Ref } from 'vue';\nimport type { ListenerOptions, IKernelEvent } from '@quazardous/quarkernel';\nimport { useKernel } from './use-kernel.js';\n\n/**\n * Options for useEventState composable\n */\nexport interface UseEventStateOptions extends Omit<ListenerOptions, 'once'> {\n  /**\n   * Transform function to extract value from event\n   * Default: returns event.data\n   */\n  transform?: (event: IKernelEvent) => any;\n}\n\n/**\n * Composable to maintain reactive state that updates on events\n *\n * Creates a Vue reactive ref that automatically updates when the specified\n * event is emitted. The listener is automatically removed when the component\n * unmounts via Vue's onUnmounted lifecycle hook.\n *\n * @template T - Value type\n * @template K - Event name type\n * @param eventName - Event name to listen for\n * @param initialValue - Initial value for the ref\n * @param options - Listener options and transform function (optional)\n * @returns Reactive ref that updates on events\n *\n * @example\n * ```ts\n * import { useEventState } from '@quazardous/quarkernel-vue';\n *\n * export default {\n *   setup() {\n *     // Simple usage - updates with event.data\n *     const userCount = useEventState('user:count', 0);\n *\n *     // With transform function\n *     const userName = useEventState(\n *       'user:login',\n *       'Guest',\n *       {\n *         transform: (event) => event.data.name\n *       }\n *     );\n *\n *     // With manual cleanup\n *     const controller = new AbortController();\n *     const status = useEventState('status', 'idle', {\n *       signal: controller.signal\n *     });\n *     // Later: controller.abort();\n *\n *     return { userCount, userName, status };\n *   }\n * }\n * ```\n */\nexport function useEventState<T = any, K extends string = string>(\n  eventName: K,\n  initialValue: T,\n  options?: UseEventStateOptions\n): Ref<T> {\n  const kernel = useKernel();\n  const state = ref<T>(initialValue) as Ref<T>;\n\n  // Extract transform function from options\n  const { transform, ...listenerOptions } = options || {};\n  const transformFn = transform || ((event: IKernelEvent) => event.data);\n\n  // Register listener that updates state\n  const unbind = kernel.on(\n    eventName,\n    (event: IKernelEvent) => {\n      state.value = transformFn(event);\n    },\n    listenerOptions\n  );\n\n  // Auto-cleanup on component unmount\n  onUnmounted(() => {\n    unbind();\n  });\n\n  return state;\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,186 @@
+import { Plugin, Ref } from 'vue';
+import { Kernel, ListenerFunction, ListenerOptions, IKernelEvent } from '@quazardous/quarkernel';
+
+/**
+ * Vue plugin for QuarKernel integration
+ *
+ * Provides global kernel instance access via Vue's provide/inject system.
+ * Use with app.use(QuarKernelPlugin, { kernel })
+ */
+
+/**
+ * Injection key for kernel instance
+ * @internal
+ */
+declare const KERNEL_INJECTION_KEY: unique symbol;
+/**
+ * Plugin options
+ */
+interface QuarKernelPluginOptions {
+    /** Kernel instance to provide globally */
+    kernel: Kernel;
+}
+/**
+ * QuarKernel Vue plugin
+ *
+ * Registers kernel instance globally for access via useKernel() composable
+ *
+ * @example
+ * ```ts
+ * import { createApp } from 'vue';
+ * import { createKernel } from '@quazardous/quarkernel';
+ * import { QuarKernelPlugin } from '@quazardous/quarkernel-vue';
+ *
+ * const kernel = createKernel();
+ * const app = createApp(App);
+ *
+ * app.use(QuarKernelPlugin, { kernel });
+ * ```
+ */
+declare const QuarKernelPlugin: Plugin;
+
+/**
+ * Vue composable for accessing QuarKernel instance
+ *
+ * Provides type-safe access to the kernel instance registered via plugin.
+ * Includes SSR guards to prevent server-side usage.
+ */
+
+/**
+ * Composable to access QuarKernel instance from components
+ *
+ * Must be called within setup() function of a component where the plugin was installed.
+ * Throws error if plugin not installed or called outside setup context.
+ * Warns when accessed during SSR.
+ *
+ * @example
+ * ```ts
+ * import { useKernel } from '@quazardous/quarkernel-vue';
+ *
+ * export default {
+ *   setup() {
+ *     const kernel = useKernel();
+ *
+ *     kernel.on('user:login', async (event) => {
+ *       console.log('User logged in:', event.data);
+ *     });
+ *
+ *     return {};
+ *   }
+ * }
+ * ```
+ */
+declare function useKernel<T extends Kernel = Kernel>(): T;
+
+/**
+ * Vue composable for event listener registration with automatic cleanup
+ *
+ * Automatically removes the listener when the component is unmounted.
+ * Supports manual cleanup via AbortSignal.
+ */
+
+/**
+ * Composable to register event listeners with automatic cleanup
+ *
+ * The listener is automatically removed when the component unmounts via Vue's
+ * onUnmounted lifecycle hook. Manual cleanup is also supported via AbortSignal.
+ *
+ * @template K - Event name type
+ * @param eventName - Event name to listen for
+ * @param handler - Listener function
+ * @param options - Listener options (optional)
+ * @returns Cleanup function to manually remove listener
+ *
+ * @example
+ * ```ts
+ * import { useOn } from '@quazardous/quarkernel-vue';
+ *
+ * export default {
+ *   setup() {
+ *     // Automatically cleaned up on unmount
+ *     useOn('user:login', async (event) => {
+ *       console.log('User logged in:', event.data);
+ *     });
+ *
+ *     // With options
+ *     useOn('data:update', handler, {
+ *       priority: 10,
+ *       id: 'my-listener'
+ *     });
+ *
+ *     // Manual cleanup via AbortSignal
+ *     const controller = new AbortController();
+ *     useOn('events', handler, {
+ *       signal: controller.signal
+ *     });
+ *     // Later: controller.abort();
+ *   }
+ * }
+ * ```
+ */
+declare function useOn<K extends string = string>(eventName: K, handler: ListenerFunction, options?: ListenerOptions): () => void;
+
+/**
+ * Vue composable for reactive event state
+ *
+ * Maintains a reactive ref that updates whenever the specified event is emitted.
+ * Automatically removes the listener when the component is unmounted.
+ */
+
+/**
+ * Options for useEventState composable
+ */
+interface UseEventStateOptions extends Omit<ListenerOptions, 'once'> {
+    /**
+     * Transform function to extract value from event
+     * Default: returns event.data
+     */
+    transform?: (event: IKernelEvent) => any;
+}
+/**
+ * Composable to maintain reactive state that updates on events
+ *
+ * Creates a Vue reactive ref that automatically updates when the specified
+ * event is emitted. The listener is automatically removed when the component
+ * unmounts via Vue's onUnmounted lifecycle hook.
+ *
+ * @template T - Value type
+ * @template K - Event name type
+ * @param eventName - Event name to listen for
+ * @param initialValue - Initial value for the ref
+ * @param options - Listener options and transform function (optional)
+ * @returns Reactive ref that updates on events
+ *
+ * @example
+ * ```ts
+ * import { useEventState } from '@quazardous/quarkernel-vue';
+ *
+ * export default {
+ *   setup() {
+ *     // Simple usage - updates with event.data
+ *     const userCount = useEventState('user:count', 0);
+ *
+ *     // With transform function
+ *     const userName = useEventState(
+ *       'user:login',
+ *       'Guest',
+ *       {
+ *         transform: (event) => event.data.name
+ *       }
+ *     );
+ *
+ *     // With manual cleanup
+ *     const controller = new AbortController();
+ *     const status = useEventState('status', 'idle', {
+ *       signal: controller.signal
+ *     });
+ *     // Later: controller.abort();
+ *
+ *     return { userCount, userName, status };
+ *   }
+ * }
+ * ```
+ */
+declare function useEventState<T = any, K extends string = string>(eventName: K, initialValue: T, options?: UseEventStateOptions): Ref<T>;
+
+export { KERNEL_INJECTION_KEY, QuarKernelPlugin, type QuarKernelPluginOptions, type UseEventStateOptions, useEventState, useKernel, useOn };

package/dist/index.d.ts

@@ -0,0 +1,186 @@
+import { Plugin, Ref } from 'vue';
+import { Kernel, ListenerFunction, ListenerOptions, IKernelEvent } from '@quazardous/quarkernel';
+
+/**
+ * Vue plugin for QuarKernel integration
+ *
+ * Provides global kernel instance access via Vue's provide/inject system.
+ * Use with app.use(QuarKernelPlugin, { kernel })
+ */
+
+/**
+ * Injection key for kernel instance
+ * @internal
+ */
+declare const KERNEL_INJECTION_KEY: unique symbol;
+/**
+ * Plugin options
+ */
+interface QuarKernelPluginOptions {
+    /** Kernel instance to provide globally */
+    kernel: Kernel;
+}
+/**
+ * QuarKernel Vue plugin
+ *
+ * Registers kernel instance globally for access via useKernel() composable
+ *
+ * @example
+ * ```ts
+ * import { createApp } from 'vue';
+ * import { createKernel } from '@quazardous/quarkernel';
+ * import { QuarKernelPlugin } from '@quazardous/quarkernel-vue';
+ *
+ * const kernel = createKernel();
+ * const app = createApp(App);
+ *
+ * app.use(QuarKernelPlugin, { kernel });
+ * ```
+ */
+declare const QuarKernelPlugin: Plugin;
+
+/**
+ * Vue composable for accessing QuarKernel instance
+ *
+ * Provides type-safe access to the kernel instance registered via plugin.
+ * Includes SSR guards to prevent server-side usage.
+ */
+
+/**
+ * Composable to access QuarKernel instance from components
+ *
+ * Must be called within setup() function of a component where the plugin was installed.
+ * Throws error if plugin not installed or called outside setup context.
+ * Warns when accessed during SSR.
+ *
+ * @example
+ * ```ts
+ * import { useKernel } from '@quazardous/quarkernel-vue';
+ *
+ * export default {
+ *   setup() {
+ *     const kernel = useKernel();
+ *
+ *     kernel.on('user:login', async (event) => {
+ *       console.log('User logged in:', event.data);
+ *     });
+ *
+ *     return {};
+ *   }
+ * }
+ * ```
+ */
+declare function useKernel<T extends Kernel = Kernel>(): T;
+
+/**
+ * Vue composable for event listener registration with automatic cleanup
+ *
+ * Automatically removes the listener when the component is unmounted.
+ * Supports manual cleanup via AbortSignal.
+ */
+
+/**
+ * Composable to register event listeners with automatic cleanup
+ *
+ * The listener is automatically removed when the component unmounts via Vue's
+ * onUnmounted lifecycle hook. Manual cleanup is also supported via AbortSignal.
+ *
+ * @template K - Event name type
+ * @param eventName - Event name to listen for
+ * @param handler - Listener function
+ * @param options - Listener options (optional)
+ * @returns Cleanup function to manually remove listener
+ *
+ * @example
+ * ```ts
+ * import { useOn } from '@quazardous/quarkernel-vue';
+ *
+ * export default {
+ *   setup() {
+ *     // Automatically cleaned up on unmount
+ *     useOn('user:login', async (event) => {
+ *       console.log('User logged in:', event.data);
+ *     });
+ *
+ *     // With options
+ *     useOn('data:update', handler, {
+ *       priority: 10,
+ *       id: 'my-listener'
+ *     });
+ *
+ *     // Manual cleanup via AbortSignal
+ *     const controller = new AbortController();
+ *     useOn('events', handler, {
+ *       signal: controller.signal
+ *     });
+ *     // Later: controller.abort();
+ *   }
+ * }
+ * ```
+ */
+declare function useOn<K extends string = string>(eventName: K, handler: ListenerFunction, options?: ListenerOptions): () => void;
+
+/**
+ * Vue composable for reactive event state
+ *
+ * Maintains a reactive ref that updates whenever the specified event is emitted.
+ * Automatically removes the listener when the component is unmounted.
+ */
+
+/**
+ * Options for useEventState composable
+ */
+interface UseEventStateOptions extends Omit<ListenerOptions, 'once'> {
+    /**
+     * Transform function to extract value from event
+     * Default: returns event.data
+     */
+    transform?: (event: IKernelEvent) => any;
+}
+/**
+ * Composable to maintain reactive state that updates on events
+ *
+ * Creates a Vue reactive ref that automatically updates when the specified
+ * event is emitted. The listener is automatically removed when the component
+ * unmounts via Vue's onUnmounted lifecycle hook.
+ *
+ * @template T - Value type
+ * @template K - Event name type
+ * @param eventName - Event name to listen for
+ * @param initialValue - Initial value for the ref
+ * @param options - Listener options and transform function (optional)
+ * @returns Reactive ref that updates on events
+ *
+ * @example
+ * ```ts
+ * import { useEventState } from '@quazardous/quarkernel-vue';
+ *
+ * export default {
+ *   setup() {
+ *     // Simple usage - updates with event.data
+ *     const userCount = useEventState('user:count', 0);
+ *
+ *     // With transform function
+ *     const userName = useEventState(
+ *       'user:login',
+ *       'Guest',
+ *       {
+ *         transform: (event) => event.data.name
+ *       }
+ *     );
+ *
+ *     // With manual cleanup
+ *     const controller = new AbortController();
+ *     const status = useEventState('status', 'idle', {
+ *       signal: controller.signal
+ *     });
+ *     // Later: controller.abort();
+ *
+ *     return { userCount, userName, status };
+ *   }
+ * }
+ * ```
+ */
+declare function useEventState<T = any, K extends string = string>(eventName: K, initialValue: T, options?: UseEventStateOptions): Ref<T>;
+
+export { KERNEL_INJECTION_KEY, QuarKernelPlugin, type QuarKernelPluginOptions, type UseEventStateOptions, useEventState, useKernel, useOn };

package/dist/index.js

@@ -0,0 +1,62 @@
+import { getCurrentInstance, inject, onUnmounted, ref } from 'vue';
+
+// src/plugin.ts
+var KERNEL_INJECTION_KEY = /* @__PURE__ */ Symbol("quarkernel");
+var QuarKernelPlugin = {
+  install(app, options) {
+    if (!options || !options.kernel) {
+      throw new Error("[QuarKernel Vue] Plugin requires a kernel instance in options");
+    }
+    app.provide(KERNEL_INJECTION_KEY, options.kernel);
+  }
+};
+function isSSR() {
+  return typeof window === "undefined";
+}
+function useKernel() {
+  const instance = getCurrentInstance();
+  if (!instance) {
+    throw new Error("[QuarKernel Vue] useKernel() must be called within setup() function");
+  }
+  if (isSSR()) {
+    console.warn(
+      "[QuarKernel Vue] useKernel() called during server-side rendering. Kernel events should typically run client-side only. Ensure you guard kernel usage in onMounted() or similar lifecycle hooks."
+    );
+  }
+  const kernel = inject(KERNEL_INJECTION_KEY);
+  if (!kernel) {
+    throw new Error(
+      "[QuarKernel Vue] Kernel instance not found. Did you install QuarKernelPlugin with app.use(QuarKernelPlugin, { kernel })?"
+    );
+  }
+  return kernel;
+}
+function useOn(eventName, handler, options) {
+  const kernel = useKernel();
+  const unbind = kernel.on(eventName, handler, options);
+  onUnmounted(() => {
+    unbind();
+  });
+  return unbind;
+}
+function useEventState(eventName, initialValue, options) {
+  const kernel = useKernel();
+  const state = ref(initialValue);
+  const { transform, ...listenerOptions } = options || {};
+  const transformFn = transform || ((event) => event.data);
+  const unbind = kernel.on(
+    eventName,
+    (event) => {
+      state.value = transformFn(event);
+    },
+    listenerOptions
+  );
+  onUnmounted(() => {
+    unbind();
+  });
+  return state;
+}
+
+export { KERNEL_INJECTION_KEY, QuarKernelPlugin, useEventState, useKernel, useOn };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/plugin.ts","../src/use-kernel.ts","../src/use-on.ts","../src/use-event-state.ts"],"names":["onUnmounted"],"mappings":";;;AAcO,IAAM,oBAAA,0BAA8B,YAAY;AA2BhD,IAAM,gBAAA,GAA2B;AAAA,EACtC,OAAA,CAAQ,KAAU,OAAA,EAAkC;AAClD,IAAA,IAAI,CAAC,OAAA,IAAW,CAAC,OAAA,CAAQ,MAAA,EAAQ;AAC/B,MAAA,MAAM,IAAI,MAAM,+DAA+D,CAAA;AAAA,IACjF;AAEA,IAAA,GAAA,CAAI,OAAA,CAAQ,oBAAA,EAAsB,OAAA,CAAQ,MAAM,CAAA;AAAA,EAClD;AACF;AClCA,SAAS,KAAA,GAAiB;AACxB,EAAA,OAAO,OAAO,MAAA,KAAW,WAAA;AAC3B;AA0BO,SAAS,SAAA,GAA0C;AAExD,EAAA,MAAM,WAAW,kBAAA,EAAmB;AACpC,EAAA,IAAI,CAAC,QAAA,EAAU;AACb,IAAA,MAAM,IAAI,MAAM,qEAAqE,CAAA;AAAA,EACvF;AAGA,EAAA,IAAI,OAAM,EAAG;AACX,IAAA,OAAA,CAAQ,IAAA;AAAA,MACN;AAAA,KAGF;AAAA,EACF;AAGA,EAAA,MAAM,MAAA,GAAS,OAAU,oBAAoB,CAAA;AAE7C,EAAA,IAAI,CAAC,MAAA,EAAQ;AACX,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,KAEF;AAAA,EACF;AAEA,EAAA,OAAO,MAAA;AACT;ACpBO,SAAS,KAAA,CACd,SAAA,EACA,OAAA,EACA,OAAA,EACY;AACZ,EAAA,MAAM,SAAS,SAAA,EAAU;AAGzB,EAAA,MAAM,MAAA,GAAS,MAAA,CAAO,EAAA,CAAG,SAAA,EAAW,SAAS,OAAO,CAAA;AAGpD,EAAA,WAAA,CAAY,MAAM;AAChB,IAAA,MAAA,EAAO;AAAA,EACT,CAAC,CAAA;AAGD,EAAA,OAAO,MAAA;AACT;ACAO,SAAS,aAAA,CACd,SAAA,EACA,YAAA,EACA,OAAA,EACQ;AACR,EAAA,MAAM,SAAS,SAAA,EAAU;AACzB,EAAA,MAAM,KAAA,GAAQ,IAAO,YAAY,CAAA;AAGjC,EAAA,MAAM,EAAE,SAAA,EAAW,GAAG,eAAA,EAAgB,GAAI,WAAW,EAAC;AACtD,EAAA,MAAM,WAAA,GAAc,SAAA,KAAc,CAAC,KAAA,KAAwB,KAAA,CAAM,IAAA,CAAA;AAGjE,EAAA,MAAM,SAAS,MAAA,CAAO,EAAA;AAAA,IACpB,SAAA;AAAA,IACA,CAAC,KAAA,KAAwB;AACvB,MAAA,KAAA,CAAM,KAAA,GAAQ,YAAY,KAAK,CAAA;AAAA,IACjC,CAAA;AAAA,IACA;AAAA,GACF;AAGA,EAAAA,YAAY,MAAM;AAChB,IAAA,MAAA,EAAO;AAAA,EACT,CAAC,CAAA;AAED,EAAA,OAAO,KAAA;AACT","file":"index.js","sourcesContent":["/**\n * Vue plugin for QuarKernel integration\n *\n * Provides global kernel instance access via Vue's provide/inject system.\n * Use with app.use(QuarKernelPlugin, { kernel })\n */\n\nimport type { App, Plugin } from 'vue';\nimport type { Kernel } from '@quazardous/quarkernel';\n\n/**\n * Injection key for kernel instance\n * @internal\n */\nexport const KERNEL_INJECTION_KEY = Symbol('quarkernel');\n\n/**\n * Plugin options\n */\nexport interface QuarKernelPluginOptions {\n  /** Kernel instance to provide globally */\n  kernel: Kernel;\n}\n\n/**\n * QuarKernel Vue plugin\n *\n * Registers kernel instance globally for access via useKernel() composable\n *\n * @example\n * ```ts\n * import { createApp } from 'vue';\n * import { createKernel } from '@quazardous/quarkernel';\n * import { QuarKernelPlugin } from '@quazardous/quarkernel-vue';\n *\n * const kernel = createKernel();\n * const app = createApp(App);\n *\n * app.use(QuarKernelPlugin, { kernel });\n * ```\n */\nexport const QuarKernelPlugin: Plugin = {\n  install(app: App, options: QuarKernelPluginOptions) {\n    if (!options || !options.kernel) {\n      throw new Error('[QuarKernel Vue] Plugin requires a kernel instance in options');\n    }\n\n    app.provide(KERNEL_INJECTION_KEY, options.kernel);\n  },\n};\n","/**\n * Vue composable for accessing QuarKernel instance\n *\n * Provides type-safe access to the kernel instance registered via plugin.\n * Includes SSR guards to prevent server-side usage.\n */\n\nimport { inject, getCurrentInstance } from 'vue';\nimport type { Kernel } from '@quazardous/quarkernel';\nimport { KERNEL_INJECTION_KEY } from './plugin.js';\n\n/**\n * Check if running in SSR context\n * @internal\n */\nfunction isSSR(): boolean {\n  return typeof window === 'undefined';\n}\n\n/**\n * Composable to access QuarKernel instance from components\n *\n * Must be called within setup() function of a component where the plugin was installed.\n * Throws error if plugin not installed or called outside setup context.\n * Warns when accessed during SSR.\n *\n * @example\n * ```ts\n * import { useKernel } from '@quazardous/quarkernel-vue';\n *\n * export default {\n *   setup() {\n *     const kernel = useKernel();\n *\n *     kernel.on('user:login', async (event) => {\n *       console.log('User logged in:', event.data);\n *     });\n *\n *     return {};\n *   }\n * }\n * ```\n */\nexport function useKernel<T extends Kernel = Kernel>(): T {\n  // Check if called within Vue component setup\n  const instance = getCurrentInstance();\n  if (!instance) {\n    throw new Error('[QuarKernel Vue] useKernel() must be called within setup() function');\n  }\n\n  // SSR guard - warn but don't block (for flexibility)\n  if (isSSR()) {\n    console.warn(\n      '[QuarKernel Vue] useKernel() called during server-side rendering. ' +\n      'Kernel events should typically run client-side only. ' +\n      'Ensure you guard kernel usage in onMounted() or similar lifecycle hooks.'\n    );\n  }\n\n  // Inject kernel instance\n  const kernel = inject<T>(KERNEL_INJECTION_KEY);\n\n  if (!kernel) {\n    throw new Error(\n      '[QuarKernel Vue] Kernel instance not found. ' +\n      'Did you install QuarKernelPlugin with app.use(QuarKernelPlugin, { kernel })?'\n    );\n  }\n\n  return kernel;\n}\n","/**\n * Vue composable for event listener registration with automatic cleanup\n *\n * Automatically removes the listener when the component is unmounted.\n * Supports manual cleanup via AbortSignal.\n */\n\nimport { onUnmounted } from 'vue';\nimport type { ListenerFunction, ListenerOptions } from '@quazardous/quarkernel';\nimport { useKernel } from './use-kernel.js';\n\n/**\n * Composable to register event listeners with automatic cleanup\n *\n * The listener is automatically removed when the component unmounts via Vue's\n * onUnmounted lifecycle hook. Manual cleanup is also supported via AbortSignal.\n *\n * @template K - Event name type\n * @param eventName - Event name to listen for\n * @param handler - Listener function\n * @param options - Listener options (optional)\n * @returns Cleanup function to manually remove listener\n *\n * @example\n * ```ts\n * import { useOn } from '@quazardous/quarkernel-vue';\n *\n * export default {\n *   setup() {\n *     // Automatically cleaned up on unmount\n *     useOn('user:login', async (event) => {\n *       console.log('User logged in:', event.data);\n *     });\n *\n *     // With options\n *     useOn('data:update', handler, {\n *       priority: 10,\n *       id: 'my-listener'\n *     });\n *\n *     // Manual cleanup via AbortSignal\n *     const controller = new AbortController();\n *     useOn('events', handler, {\n *       signal: controller.signal\n *     });\n *     // Later: controller.abort();\n *   }\n * }\n * ```\n */\nexport function useOn<K extends string = string>(\n  eventName: K,\n  handler: ListenerFunction,\n  options?: ListenerOptions\n): () => void {\n  const kernel = useKernel();\n\n  // Register listener on kernel\n  const unbind = kernel.on(eventName, handler, options);\n\n  // Auto-cleanup on component unmount\n  onUnmounted(() => {\n    unbind();\n  });\n\n  // Return unbind for manual cleanup\n  return unbind;\n}\n","/**\n * Vue composable for reactive event state\n *\n * Maintains a reactive ref that updates whenever the specified event is emitted.\n * Automatically removes the listener when the component is unmounted.\n */\n\nimport { ref, onUnmounted } from 'vue';\nimport type { Ref } from 'vue';\nimport type { ListenerOptions, IKernelEvent } from '@quazardous/quarkernel';\nimport { useKernel } from './use-kernel.js';\n\n/**\n * Options for useEventState composable\n */\nexport interface UseEventStateOptions extends Omit<ListenerOptions, 'once'> {\n  /**\n   * Transform function to extract value from event\n   * Default: returns event.data\n   */\n  transform?: (event: IKernelEvent) => any;\n}\n\n/**\n * Composable to maintain reactive state that updates on events\n *\n * Creates a Vue reactive ref that automatically updates when the specified\n * event is emitted. The listener is automatically removed when the component\n * unmounts via Vue's onUnmounted lifecycle hook.\n *\n * @template T - Value type\n * @template K - Event name type\n * @param eventName - Event name to listen for\n * @param initialValue - Initial value for the ref\n * @param options - Listener options and transform function (optional)\n * @returns Reactive ref that updates on events\n *\n * @example\n * ```ts\n * import { useEventState } from '@quazardous/quarkernel-vue';\n *\n * export default {\n *   setup() {\n *     // Simple usage - updates with event.data\n *     const userCount = useEventState('user:count', 0);\n *\n *     // With transform function\n *     const userName = useEventState(\n *       'user:login',\n *       'Guest',\n *       {\n *         transform: (event) => event.data.name\n *       }\n *     );\n *\n *     // With manual cleanup\n *     const controller = new AbortController();\n *     const status = useEventState('status', 'idle', {\n *       signal: controller.signal\n *     });\n *     // Later: controller.abort();\n *\n *     return { userCount, userName, status };\n *   }\n * }\n * ```\n */\nexport function useEventState<T = any, K extends string = string>(\n  eventName: K,\n  initialValue: T,\n  options?: UseEventStateOptions\n): Ref<T> {\n  const kernel = useKernel();\n  const state = ref<T>(initialValue) as Ref<T>;\n\n  // Extract transform function from options\n  const { transform, ...listenerOptions } = options || {};\n  const transformFn = transform || ((event: IKernelEvent) => event.data);\n\n  // Register listener that updates state\n  const unbind = kernel.on(\n    eventName,\n    (event: IKernelEvent) => {\n      state.value = transformFn(event);\n    },\n    listenerOptions\n  );\n\n  // Auto-cleanup on component unmount\n  onUnmounted(() => {\n    unbind();\n  });\n\n  return state;\n}\n"]}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@quazardous/quarkernel-vue",
+  "version": "2.1.0",
+  "type": "module",
+  "description": "Vue 3 adapter for QuarKernel - event kernel integration with Vue reactivity",
+  "author": "quazardous <berliozdavid@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/quazardous/quarkernel.git",
+    "directory": "packages/vue"
+  },
+  "bugs": {
+    "url": "https://github.com/quazardous/quarkernel/issues"
+  },
+  "homepage": "https://github.com/quazardous/quarkernel#readme",
+  "keywords": [
+    "quarkernel",
+    "vue",
+    "vue3",
+    "event",
+    "events",
+    "kernel",
+    "composable",
+    "plugin",
+    "reactivity"
+  ],
+  "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",
+    "vue": "^3.3.0"
+  },
+  "devDependencies": {
+    "@quazardous/quarkernel": "file:../quarkernel",
+    "jsdom": "^23.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0",
+    "vue": "^3.3.0"
+  }
+}