@pyreon/vue-compat 0.13.1 → 0.15.0

package/lib/types/index.d.ts

@@ -1,4 +1,4 @@
-import { ComponentFn, Fragment, Props, VNodeChild, h as pyreonH } from "@pyreon/core";
+import { ComponentFn, ComponentFn as Component, Fragment, Props, VNodeChild, VNodeChild as VNode, h as pyreonH } from "@pyreon/core";
 import { batch } from "@pyreon/reactivity";
 
 //#region src/index.d.ts
@@ -31,6 +31,11 @@ declare function isRef(val: unknown): val is Ref;
  * Unwraps a ref: if it has `.value`, return `.value`; otherwise return as-is.
  */
 declare function unref<T>(r: T | Ref<T>): T;
+/**
+ * Unwraps a ref, calls a getter, or returns the value as-is.
+ * Vue 3.3+ API for normalizing ref/getter/value inputs.
+ */
+declare function toValue<T>(source: Ref<T> | (() => T) | T): T;
 interface ComputedRef<T = unknown> extends Ref<T> {
   readonly value: T;
 }
@@ -65,6 +70,11 @@ declare function shallowReactive<T extends object>(obj: T): T;
  * Inside a component: hook-indexed.
  */
 declare function readonly<T extends object>(obj: T): Readonly<T>;
+/**
+ * Returns a shallow readonly proxy — only top-level properties throw on set.
+ * Nested objects are NOT wrapped in readonly (unlike `readonly()`).
+ */
+declare function shallowReadonly<T extends object>(obj: T): Readonly<T>;
 /**
  * Returns the raw (unwrapped) object behind a reactive or readonly proxy.
  */
@@ -88,21 +98,25 @@ interface WatchOptions {
   immediate?: boolean;
   /** Ignored in Pyreon — dependencies are tracked automatically. */
   deep?: boolean;
+  /** Accepted for compatibility but not meaningfully differentiated in Pyreon. */
+  flush?: 'pre' | 'post' | 'sync';
 }
 type WatchSource<T> = Ref<T> | (() => T);
 /**
- * Watches a reactive source and calls `cb` when it changes.
+ * Watches a reactive source (or array of sources) and calls `cb` when it changes.
  *
  * Inside a component: hook-indexed, created once. Disposed on unmount.
  */
-declare function watch<T>(source: WatchSource<T>, cb: (newValue: T, oldValue: T | undefined) => void, options?: WatchOptions): () => void;
+declare function watch<T>(source: WatchSource<T>, cb: (newValue: T, oldValue: T | undefined, onCleanup: (fn: () => void) => void) => void, options?: WatchOptions): () => void;
+declare function watch<T extends readonly WatchSource<any>[]>(sources: [...T], cb: (newValues: { [K in keyof T]: T[K] extends WatchSource<infer V> ? V : never }, oldValues: { [K in keyof T]: T[K] extends WatchSource<infer V> ? V | undefined : never }, onCleanup: (fn: () => void) => void) => void, options?: WatchOptions): () => void;
 /**
  * Runs the given function reactively — re-executes whenever its tracked
- * dependencies change.
+ * dependencies change. Passes an `onCleanup` registration function to the
+ * callback, matching Vue 3's `watchEffect((onCleanup) => { ... })` API.
  *
  * Inside a component: hook-indexed, created once. Disposed on unmount.
  */
-declare function watchEffect(fn: () => void): () => void;
+declare function watchEffect(fn: (onCleanup: (fn: () => void) => void) => void): () => void;
 /**
  * Registers a callback to run after the component is mounted.
  * Hook-indexed: only registered on first render.
@@ -140,27 +154,173 @@ declare function nextTick(): Promise<void>;
 declare function provide<T>(key: string | symbol, value: T): void;
 /**
  * Injects a value provided by an ancestor component.
+ * Supports Vue 3's factory default pattern: `inject(key, () => expensiveDefault, true)`.
  */
-declare function inject<T>(key: string | symbol, defaultValue?: T): T | undefined;
+declare function inject<T>(key: string | symbol, defaultValue?: T | (() => T), treatDefaultAsFactory?: boolean): T | undefined;
 interface ComponentOptions<P extends Props = Props> {
   /** The setup function — called once during component initialization. */
-  setup: (props: P) => (() => VNodeChild) | VNodeChild;
+  setup: (props: P, ctx?: SetupContext) => (() => VNodeChild) | VNodeChild;
   /** Optional name for debugging. */
   name?: string;
+  /** Prop definitions (not validated at runtime, used for type documentation). */
+  props?: Record<string, unknown>;
 }
 /**
  * Defines a component using Vue 3 Composition API style.
  * Only supports the `setup()` function — Options API is not supported.
  */
 declare function defineComponent<P extends Props = Props>(options: ComponentOptions<P> | ((props: P) => VNodeChild)): ComponentFn<P>;
+/**
+ * Defines an async component that lazily loads on first use.
+ * Supports both a bare loader function and an options object with
+ * loadingComponent, errorComponent, delay, and timeout.
+ *
+ * Returns a ComponentFn with a `__loading` property for Suspense integration.
+ */
+declare function defineAsyncComponent<P extends Props = Props>(loader: (() => Promise<{
+  default: ComponentFn<P>;
+}>) | {
+  loader: () => Promise<{
+    default: ComponentFn<P>;
+  }>;
+  loadingComponent?: ComponentFn;
+  errorComponent?: ComponentFn;
+  delay?: number;
+  timeout?: number;
+}): ComponentFn<P> & {
+  __loading: () => boolean;
+};
 interface App {
   /** Mount the application into a DOM element. Returns an unmount function. */
   mount(el: string | Element): () => void;
+  /** Install a plugin. */
+  use(plugin: {
+    install: (app: App) => void;
+  }): App;
+  /** Provide a value to the entire app tree. */
+  provide<T>(key: string | symbol, value: T): App;
 }
 /**
  * Creates a Pyreon application instance — Vue 3 `createApp()` compatible.
  */
 declare function createApp(component: ComponentFn, props?: Props): App;
+/**
+ * Returns `true` if the value was created by `reactive()`.
+ */
+declare function isReactive(value: unknown): boolean;
+/**
+ * Returns `true` if the value was created by `readonly()`.
+ */
+declare function isReadonly(value: unknown): boolean;
+/**
+ * Returns `true` if the value is either reactive or readonly.
+ */
+declare function isProxy(value: unknown): boolean;
+/**
+ * Marks an object so that `reactive()` will return it as-is (not wrapped).
+ */
+declare function markRaw<T extends object>(obj: T): T;
+interface EffectScopeCompat {
+  /** Run a function within this scope. Returns undefined if scope is stopped. */
+  run<T>(fn: () => T): T | undefined;
+  /** Stop the scope and dispose all collected effects/cleanups. */
+  stop(): void;
+  /** Whether the scope is still active. */
+  active: boolean;
+}
+/**
+ * Creates an effect scope that collects reactive effects for grouped disposal.
+ *
+ * @param detached - If true, the scope is not collected by a parent scope.
+ */
+declare function effectScope(detached?: boolean): EffectScopeCompat;
+/**
+ * Returns the current active effect scope, or undefined if none.
+ */
+declare function getCurrentScope(): EffectScopeCompat | undefined;
+/**
+ * Registers a cleanup function on the current effect scope.
+ */
+declare function onScopeDispose(fn: () => void): void;
+/**
+ * Registers an error capture handler.
+ * No direct equivalent in Pyreon — stored but not actively used.
+ */
+declare function onErrorCaptured(fn: (err: Error) => boolean | void): void;
+/**
+ * Dev-only lifecycle hook — no-op in Pyreon.
+ */
+declare function onRenderTracked(_fn: (event: {
+  key: string;
+  type: string;
+}) => void): void;
+/**
+ * Dev-only lifecycle hook — no-op in Pyreon.
+ */
+declare function onRenderTriggered(_fn: (event: {
+  key: string;
+  type: string;
+}) => void): void;
+/**
+ * Teleport — renders children into a different DOM element.
+ * Maps to Pyreon's Portal.
+ */
+declare function Teleport(props: {
+  to: string | Element;
+  children?: VNodeChild;
+}): VNodeChild;
+/**
+ * KeepAlive — not supported in Pyreon. Renders children as-is.
+ */
+declare function KeepAlive(props: {
+  children?: VNodeChild;
+}): VNodeChild;
+/**
+ * Runs a watchEffect that flushes after DOM updates.
+ * In Pyreon, same as `watchEffect()`.
+ */
+declare function watchPostEffect(fn: (onCleanup: (fn: () => void) => void) => void): () => void;
+/**
+ * Runs a watchEffect that flushes synchronously.
+ * In Pyreon, same as `watchEffect()`.
+ */
+declare function watchSyncEffect(fn: (onCleanup: (fn: () => void) => void) => void): () => void;
+/**
+ * Creates a customized ref with explicit control over dependency tracking
+ * and update triggering.
+ */
+declare function customRef<T>(factory: (track: () => void, trigger: () => void) => {
+  get: () => T;
+  set: (v: T) => void;
+}): Ref<T>;
+/**
+ * Compatibility version string — indicates Vue 3 API compatibility.
+ */
+declare const version = "3.5.0-pyreon";
+/** Vue-compatible PropType — a callable that returns T. */
+type PropType<T> = {
+  (): T;
+};
+/** Extract prop types from a component's props definition. */
+type ExtractPropTypes<T> = { [K in keyof T]: T[K] extends PropType<infer V> ? V : T[K] };
+/** Vue-compatible emits options type. */
+type EmitsOptions = Record<string, (...args: unknown[]) => void>;
+/** Vue-compatible setup context. */
+type SetupContext = {
+  emit: (event: string, ...args: unknown[]) => void;
+  slots: Record<string, (() => VNodeChild) | undefined>;
+  attrs: Record<string, unknown>;
+};
+/** Vue-compatible plugin interface. */
+type Plugin = {
+  install: (app: App) => void;
+};
+/** Vue-compatible directive type (stub). */
+type Directive = Record<string, unknown>;
+/** Vue-compatible injection key with type branding. */
+type InjectionKey<T> = symbol & {
+  __type: T;
+};
 //#endregion
-export { ComputedRef, Fragment, Ref, WatchOptions, WritableComputedRef, batch, computed, createApp, defineComponent, pyreonH as h, inject, isRef, nextTick, onBeforeMount, onBeforeUnmount, onMounted, onUnmounted, onUpdated, provide, reactive, readonly, ref, shallowReactive, shallowRef, toRaw, toRef, toRefs, triggerRef, unref, watch, watchEffect };
+export { type Component, ComputedRef, Directive, EffectScopeCompat, EmitsOptions, ExtractPropTypes, Fragment, InjectionKey, KeepAlive, Plugin, PropType, Ref, SetupContext, Teleport, type VNode, WatchOptions, WritableComputedRef, batch, computed, createApp, customRef, defineAsyncComponent, defineComponent, effectScope, getCurrentScope, pyreonH as h, inject, isProxy, isReactive, isReadonly, isRef, markRaw, nextTick, onBeforeMount, onBeforeUnmount, onErrorCaptured, onMounted, onRenderTracked, onRenderTriggered, onScopeDispose, onUnmounted, onUpdated, provide, reactive, readonly, ref, shallowReactive, shallowReadonly, shallowRef, toRaw, toRef, toRefs, toValue, triggerRef, unref, version, watch, watchEffect, watchPostEffect, watchSyncEffect };
 //# sourceMappingURL=index2.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/vue-compat",
-  "version": "0.13.1",
+  "version": "0.15.0",
   "description": "Vue 3-compatible Composition API shim for Pyreon — write Vue-style code that runs on Pyreon's reactive engine",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/vue-compat#readme",
   "bugs": {
@@ -14,6 +14,7 @@
   },
   "files": [
     "lib",
+    "!lib/**/*.map",
     "src",
     "README.md",
     "LICENSE"
@@ -47,17 +48,20 @@
     "build": "vl_rolldown_build",
     "dev": "vl_rolldown_build-watch",
     "test": "vitest run",
+    "test:browser": "vitest run --config ./vitest.browser.config.ts",
     "typecheck": "tsc --noEmit",
     "lint": "oxlint .",
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@pyreon/core": "^0.13.1",
-    "@pyreon/reactivity": "^0.13.1",
-    "@pyreon/runtime-dom": "^0.13.1"
+    "@pyreon/core": "^0.15.0",
+    "@pyreon/reactivity": "^0.15.0",
+    "@pyreon/runtime-dom": "^0.15.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.8.9",
+    "@pyreon/test-utils": "^0.13.2",
+    "@vitest/browser-playwright": "^4.1.4",
     "happy-dom": "^20.8.3"
   }
 }