@pyreon/vue-compat 0.18.0 → 0.19.0

package/src/index.ts

@@ -32,6 +32,7 @@ import {
   Portal,
   pushContext,
   h as pyreonH,
+  Suspense as PyreonSuspense,
   useContext,
 } from '@pyreon/core'
 import {
@@ -42,7 +43,12 @@ import {
   type Signal,
   signal,
 } from '@pyreon/reactivity'
-import { mount as pyreonMount } from '@pyreon/runtime-dom'
+import {
+  KeepAlive as PyreonKeepAlive,
+  mount as pyreonMount,
+  Transition as PyreonTransition,
+  TransitionGroup as PyreonTransitionGroup,
+} from '@pyreon/runtime-dom'
 import { getCurrentCtx, getHookIndex } from './jsx-runtime'
 
 // ─── Internal symbols ─────────────────────────────────────────────────────────
@@ -918,6 +924,27 @@ interface ComponentOptions<P extends Props = Props> {
   props?: Record<string, unknown>
 }
 
+/**
+ * Computes Vue's fallthrough `attrs` — every passed prop that is NOT a
+ * declared prop (and not the internal `children` slot payload). When the
+ * component declared no props (`declared` undefined) the split is unknowable,
+ * so the full props object is returned (honest back-compat — matches the
+ * pre-split behavior rather than guessing).
+ */
+function splitVueAttrs(
+  props: Record<string, unknown>,
+  declared: string[] | undefined,
+): Record<string, unknown> {
+  if (!declared) return props
+  const declaredSet = new Set(declared)
+  const attrs: Record<string, unknown> = {}
+  for (const key of Object.keys(props)) {
+    if (key === 'children' || declaredSet.has(key)) continue
+    attrs[key] = props[key]
+  }
+  return attrs
+}
+
 /**
  * Defines a component using Vue 3 Composition API style.
  * Only supports the `setup()` function — Options API is not supported.
@@ -928,9 +955,15 @@ export function defineComponent<P extends Props = Props>(
   if (typeof options === 'function') {
     return options as ComponentFn<P>
   }
+  const declaredProps = options.props ? Object.keys(options.props) : undefined
   const comp = (props: P) => {
     // Extract children from props for slots
     const children = (props as Record<string, unknown>).children as VNodeChild | undefined
+    // Publish the declared-prop names on the active render context so the
+    // standalone useAttrs() / getCurrentInstance() can compute the Vue
+    // declared-vs-fallthrough split (Vue's `attrs` excludes declared props).
+    const rc = getCurrentCtx()
+    if (rc && declaredProps) rc._declaredProps = declaredProps
     // Create a minimal SetupContext
     const setupCtx: SetupContext = {
       emit: (event: string, ...args: unknown[]) => {
@@ -941,7 +974,7 @@ export function defineComponent<P extends Props = Props>(
       slots: {
         default: children !== undefined ? (() => children) : undefined,
       } as Record<string, (() => VNodeChild) | undefined>,
-      attrs: props as Record<string, unknown>,
+      attrs: splitVueAttrs(props as Record<string, unknown>, declaredProps),
     }
     const result = options.setup(props, setupCtx)
     if (typeof result === 'function') {
@@ -1216,10 +1249,402 @@ export function Teleport(props: {
 }
 
 /**
- * KeepAlive — not supported in Pyreon. Renders children as-is.
+ * KeepAlive — mounts its children once and keeps them alive (state preserved)
+ * even when hidden, instead of destroying/recreating them.
+ *
+ * Wraps `@pyreon/runtime-dom`'s real KeepAlive. Vue's `<KeepAlive>` keeps a
+ * cache of inactive component instances; this maps the common single-slot
+ * usage to Pyreon's `active`-accessor model.
+ *
+ * LIMITATIONS vs Vue 3:
+ *  - Vue's `include` / `exclude` / `max` props are NOT supported. Pyreon's
+ *    KeepAlive is a single always-mounted slot toggled by an `active`
+ *    accessor — there is no per-component LRU cache to filter or bound.
+ *    These props are accepted (so existing Vue code typechecks) but ignored.
+ *  - Vue toggles activation via the dynamic child (`<component :is>`); here
+ *    you pass an `active` accessor (`() => boolean`). When omitted, children
+ *    are always mounted and visible (a faithful default — nothing is
+ *    destroyed, matching KeepAlive's core guarantee).
+ *
+ * @example
+ * import { KeepAlive, ref } from "@pyreon/vue-compat"
+ *
+ * function App() {
+ *   const showA = ref(true)
+ *   return (
+ *     <KeepAlive active={() => showA.value}>
+ *       <ExpensiveTab />
+ *     </KeepAlive>
+ *   )
+ * }
+ */
+export function KeepAlive(props: {
+  active?: () => boolean
+  /** Accepted for Vue compatibility — ignored (no per-instance cache). */
+  include?: string | RegExp | (string | RegExp)[]
+  /** Accepted for Vue compatibility — ignored (no per-instance cache). */
+  exclude?: string | RegExp | (string | RegExp)[]
+  /** Accepted for Vue compatibility — ignored (no per-instance cache). */
+  max?: number
+  children?: VNodeChild
+}): VNodeChild {
+  return PyreonKeepAlive({
+    ...(props.active !== undefined ? { active: props.active } : {}),
+    children: props.children ?? null,
+  })
+}
+
+// ─── Transition / TransitionGroup ────────────────────────────────────────────
+
+/**
+ * Transition — adds CSS enter/leave animation classes to a single child,
+ * controlled by a reactive `show` accessor.
+ *
+ * Wraps `@pyreon/runtime-dom`'s Transition. Vue's class-name conventions
+ * (`enter-from-class`, `enter-active-class`, …) are mapped onto Pyreon's
+ * (`enterFrom`, `enterActive`, …), and Vue's `@before-enter` / `@after-enter`
+ * style hooks are mapped onto Pyreon's `onBeforeEnter` / `onAfterEnter`.
+ *
+ * LIMITATIONS vs Vue 3:
+ *  - Vue's `<Transition>` infers visibility from a `v-if` / `v-show` on its
+ *    child. Pyreon has no template directives, so you MUST pass an explicit
+ *    `show: () => boolean` accessor. Without it the child is shown
+ *    unconditionally (no enter/leave is ever triggered).
+ *  - `mode` ("out-in" / "in-out"), `css: false`, and JS-only hook-driven
+ *    transitions are NOT supported — Pyreon's Transition is CSS-class based.
+ *    The props are accepted for typechecking but ignored.
+ *  - The Vue `name` convention (`name="fade"` → `fade-enter-from` …) is
+ *    preserved 1:1 (Pyreon uses the identical class-name scheme).
+ *
+ * @example
+ * import { Transition, ref } from "@pyreon/vue-compat"
+ *
+ * function App() {
+ *   const visible = ref(false)
+ *   return (
+ *     <Transition name="fade" show={() => visible.value}>
+ *       <div class="modal">Hello</div>
+ *     </Transition>
+ *   )
+ * }
+ * // CSS:
+ * //   .fade-enter-from, .fade-leave-to     { opacity: 0; }
+ * //   .fade-enter-active, .fade-leave-active { transition: opacity 300ms; }
+ */
+export function Transition(props: {
+  name?: string
+  show?: () => boolean
+  appear?: boolean
+  /** Vue class-name prop — mapped to Pyreon's `enterFrom`. */
+  enterFromClass?: string
+  /** Vue class-name prop — mapped to Pyreon's `enterActive`. */
+  enterActiveClass?: string
+  /** Vue class-name prop — mapped to Pyreon's `enterTo`. */
+  enterToClass?: string
+  /** Vue class-name prop — mapped to Pyreon's `leaveFrom`. */
+  leaveFromClass?: string
+  /** Vue class-name prop — mapped to Pyreon's `leaveActive`. */
+  leaveActiveClass?: string
+  /** Vue class-name prop — mapped to Pyreon's `leaveTo`. */
+  leaveToClass?: string
+  /** Accepted for Vue compatibility — ignored (CSS-class transitions only). */
+  mode?: 'in-out' | 'out-in' | 'default'
+  /** Accepted for Vue compatibility — ignored (CSS-class transitions only). */
+  css?: boolean
+  onBeforeEnter?: (el: HTMLElement) => void
+  onAfterEnter?: (el: HTMLElement) => void
+  onBeforeLeave?: (el: HTMLElement) => void
+  onAfterLeave?: (el: HTMLElement) => void
+  children?: VNodeChild
+}): VNodeChild {
+  return PyreonTransition({
+    show: props.show ?? (() => true),
+    ...(props.name !== undefined ? { name: props.name } : {}),
+    ...(props.appear !== undefined ? { appear: props.appear } : {}),
+    ...(props.enterFromClass !== undefined ? { enterFrom: props.enterFromClass } : {}),
+    ...(props.enterActiveClass !== undefined ? { enterActive: props.enterActiveClass } : {}),
+    ...(props.enterToClass !== undefined ? { enterTo: props.enterToClass } : {}),
+    ...(props.leaveFromClass !== undefined ? { leaveFrom: props.leaveFromClass } : {}),
+    ...(props.leaveActiveClass !== undefined ? { leaveActive: props.leaveActiveClass } : {}),
+    ...(props.leaveToClass !== undefined ? { leaveTo: props.leaveToClass } : {}),
+    ...(props.onBeforeEnter !== undefined ? { onBeforeEnter: props.onBeforeEnter } : {}),
+    ...(props.onAfterEnter !== undefined ? { onAfterEnter: props.onAfterEnter } : {}),
+    ...(props.onBeforeLeave !== undefined ? { onBeforeLeave: props.onBeforeLeave } : {}),
+    ...(props.onAfterLeave !== undefined ? { onAfterLeave: props.onAfterLeave } : {}),
+    children: props.children ?? null,
+  })
+}
+
+/**
+ * TransitionGroup — animates a keyed reactive list with CSS enter/leave plus
+ * FLIP move animations.
+ *
+ * Wraps `@pyreon/runtime-dom`'s TransitionGroup. Vue's class-name props are
+ * mapped onto Pyreon's, same as {@link Transition}.
+ *
+ * LIMITATIONS vs Vue 3:
+ *  - Vue's `<TransitionGroup>` renders its children via slots and reads keys
+ *    from the child VNode `key`. Pyreon's API is explicit: pass `items`
+ *    (a reactive accessor), `keyFn` (stable key extractor), and `render`
+ *    (returns one DOM-element VNode per item). This is the faithful Pyreon
+ *    shape — the animation behavior (enter/leave/FLIP-move) is identical.
+ *  - `mode` and `css: false` are NOT supported (CSS-class transitions only).
+ *
+ * @example
+ * import { TransitionGroup, ref } from "@pyreon/vue-compat"
+ *
+ * function App() {
+ *   const items = ref([{ id: 1 }, { id: 2 }])
+ *   return (
+ *     <TransitionGroup
+ *       tag="ul"
+ *       name="list"
+ *       items={() => items.value}
+ *       keyFn={(it) => it.id}
+ *       render={(it) => <li class="item">{it.id}</li>}
+ *     />
+ *   )
+ * }
+ */
+export function TransitionGroup<T = unknown>(props: {
+  tag?: string
+  name?: string
+  appear?: boolean
+  enterFromClass?: string
+  enterActiveClass?: string
+  enterToClass?: string
+  leaveFromClass?: string
+  leaveActiveClass?: string
+  leaveToClass?: string
+  /** Vue class-name prop — mapped to Pyreon's `moveClass`. */
+  moveClass?: string
+  items: () => T[]
+  keyFn: (item: T, index: number) => string | number
+  render: (item: T, index: number) => ReturnType<typeof pyreonH>
+  onBeforeEnter?: (el: HTMLElement) => void
+  onAfterEnter?: (el: HTMLElement) => void
+  onBeforeLeave?: (el: HTMLElement) => void
+  onAfterLeave?: (el: HTMLElement) => void
+}): VNodeChild {
+  return PyreonTransitionGroup<T>({
+    items: props.items,
+    keyFn: props.keyFn,
+    render: props.render,
+    ...(props.tag !== undefined ? { tag: props.tag } : {}),
+    ...(props.name !== undefined ? { name: props.name } : {}),
+    ...(props.appear !== undefined ? { appear: props.appear } : {}),
+    ...(props.enterFromClass !== undefined ? { enterFrom: props.enterFromClass } : {}),
+    ...(props.enterActiveClass !== undefined ? { enterActive: props.enterActiveClass } : {}),
+    ...(props.enterToClass !== undefined ? { enterTo: props.enterToClass } : {}),
+    ...(props.leaveFromClass !== undefined ? { leaveFrom: props.leaveFromClass } : {}),
+    ...(props.leaveActiveClass !== undefined ? { leaveActive: props.leaveActiveClass } : {}),
+    ...(props.leaveToClass !== undefined ? { leaveTo: props.leaveToClass } : {}),
+    ...(props.moveClass !== undefined ? { moveClass: props.moveClass } : {}),
+    ...(props.onBeforeEnter !== undefined ? { onBeforeEnter: props.onBeforeEnter } : {}),
+    ...(props.onAfterEnter !== undefined ? { onAfterEnter: props.onAfterEnter } : {}),
+    ...(props.onBeforeLeave !== undefined ? { onBeforeLeave: props.onBeforeLeave } : {}),
+    ...(props.onAfterLeave !== undefined ? { onAfterLeave: props.onAfterLeave } : {}),
+  })
+}
+
+// ─── Suspense ────────────────────────────────────────────────────────────────
+
+/**
+ * Suspense — shows `fallback` content while an async (lazy) child is loading.
+ *
+ * Re-exports `@pyreon/core`'s Suspense. Vue 3's `<Suspense>` uses named
+ * `#default` / `#fallback` slots; this maps the `fallback` slot to Pyreon
+ * Suspense's `fallback` prop and the default slot to `children`.
+ *
+ * LIMITATIONS vs Vue 3:
+ *  - Vue resolves `<Suspense>` against any `async setup()` in the subtree and
+ *    supports `@resolve` / `@pending` / `@fallback` events plus the `timeout`
+ *    prop. Pyreon's Suspense resolves against components carrying a
+ *    `__loading` accessor (e.g. {@link defineAsyncComponent} output) and does
+ *    not emit those events. The events / `timeout` prop are accepted for
+ *    typechecking but ignored.
+ *
+ * @example
+ * import { Suspense, defineAsyncComponent } from "@pyreon/vue-compat"
+ *
+ * const AsyncPage = defineAsyncComponent(() => import("./Page"))
+ *
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<div>Loading…</div>}>
+ *       <AsyncPage />
+ *     </Suspense>
+ *   )
+ * }
  */
-export function KeepAlive(props: { children?: VNodeChild }): VNodeChild {
-  return props.children ?? null
+export function Suspense(props: {
+  fallback?: VNodeChild
+  /** Accepted for Vue compatibility — ignored (no timeout phase). */
+  timeout?: number
+  children?: VNodeChild
+}): VNodeChild {
+  return PyreonSuspense({
+    fallback: props.fallback ?? null,
+    children: props.children ?? null,
+  })
+}
+
+// ─── getCurrentInstance / useSlots / useAttrs ────────────────────────────────
+
+/**
+ * Vue-compatible component-instance handle.
+ *
+ * Backed by the compat hook-context. Only the fields commonly read by
+ * composable libraries are populated. See {@link getCurrentInstance}.
+ */
+export interface ComponentInternalInstance {
+  /** Monotonic per-instance id. */
+  uid: number
+  /**
+   * Vue's `proxy` — the component public instance. In this shim it is an
+   * empty object (Pyreon components are plain functions; there is no
+   * `this`-bound options instance). Present so `inst.proxy` access doesn't
+   * throw; do not rely on reading reactive state off it.
+   */
+  proxy: Record<string, unknown>
+  /** Slots derived from the current component's children. */
+  slots: Record<string, (() => VNodeChild) | undefined>
+  /** Fallthrough attrs (declared props excluded — mirrors `useAttrs()`). */
+  attrs: Record<string, unknown>
+  /**
+   * Emits an event by invoking the matching `on{Event}` prop handler —
+   * same behavior as the `emit` on `defineComponent`'s setup context.
+   * Libraries that call `instance.emit(...)` (vee-validate, etc.) work.
+   */
+  emit: (event: string, ...args: unknown[]) => void
+  /** `true` — present for libraries that branch on `isMounted`-like flags. */
+  isMounted: boolean
+  /** @internal — the underlying compat render context. */
+  _ctx: ReturnType<typeof getCurrentCtx>
+}
+
+let _instanceUid = 0
+
+/**
+ * Returns a handle to the current component instance, or `null` if called
+ * outside a component setup.
+ *
+ * Vue 3's `getCurrentInstance()` is an internal API many composable libraries
+ * (vee-validate, vue-i18n, pinia plugins, …) read for `uid`, `proxy`, `slots`,
+ * `attrs`. This shim returns a minimal stable object with those fields so such
+ * libraries don't crash.
+ *
+ * LIMITATIONS vs Vue 3:
+ *  - `proxy` is an empty object — Pyreon components are plain functions with
+ *    no `this`-bound Options instance. Code that reads reactive state off
+ *    `instance.proxy.$data` / `.$props` will not work; use `props` directly.
+ *  - `instance.emit(event, ...args)` IS provided (invokes the matching
+ *    `on{Event}` prop handler). `instance.attrs` is the fallthrough split
+ *    (declared props excluded) when the component used `defineComponent({
+ *    props })`; otherwise it is the full props object.
+ *  - `appContext`, `parent`, `vnode`, `expose`, render internals are NOT
+ *    provided. Libraries that walk the parent chain are not supported.
+ *  - The same `uid` is stable across re-renders of the same instance
+ *    (hook-indexed), matching Vue's per-instance-id guarantee.
+ *
+ * @example
+ * import { getCurrentInstance } from "@pyreon/vue-compat"
+ *
+ * function useUid() {
+ *   const inst = getCurrentInstance()
+ *   return inst ? inst.uid : -1
+ * }
+ */
+export function getCurrentInstance(): ComponentInternalInstance | null {
+  const ctx = getCurrentCtx()
+  if (!ctx) return null
+
+  const idx = getHookIndex()
+  if (idx < ctx.hooks.length) {
+    return ctx.hooks[idx] as ComponentInternalInstance
+  }
+
+  const props = ctx._props ?? {}
+  const children = (props as Record<string, unknown>).children as VNodeChild | undefined
+  const instance: ComponentInternalInstance = {
+    uid: _instanceUid++,
+    proxy: {},
+    slots: {
+      default: children !== undefined ? () => children : undefined,
+    },
+    attrs: splitVueAttrs(props, ctx._declaredProps),
+    emit: (event: string, ...args: unknown[]) => {
+      const handlerKey = `on${event.charAt(0).toUpperCase()}${event.slice(1)}`
+      const handler = (props as Record<string, unknown>)[handlerKey]
+      if (typeof handler === 'function') (handler as (...a: unknown[]) => void)(...args)
+    },
+    isMounted: true,
+    _ctx: ctx,
+  }
+  ctx.hooks[idx] = instance
+  return instance
+}
+
+/**
+ * Returns the current component's slots — a map of slot-name → render
+ * function. Only the `default` slot is populated (derived from `children`),
+ * matching how `@pyreon/vue-compat` models slots elsewhere
+ * ({@link defineComponent}'s setup context).
+ *
+ * LIMITATIONS vs Vue 3:
+ *  - Vue supports arbitrary named + scoped slots resolved from the parent
+ *    template. Pyreon passes a single `children` payload, so only
+ *    `slots.default` is available. Named/scoped slots are not modeled.
+ *  - Returns an empty object (no `default`) when there are no children or
+ *    when called outside a component.
+ *
+ * @example
+ * import { useSlots } from "@pyreon/vue-compat"
+ *
+ * function Wrapper() {
+ *   const slots = useSlots()
+ *   return <div class="box">{slots.default?.()}</div>
+ * }
+ */
+export function useSlots(): Record<string, (() => VNodeChild) | undefined> {
+  const ctx = getCurrentCtx()
+  if (!ctx) return {}
+  const props = ctx._props ?? {}
+  const children = (props as Record<string, unknown>).children as VNodeChild | undefined
+  if (children === undefined) return {}
+  return { default: () => children }
+}
+
+/**
+ * Returns the current component's non-prop attributes.
+ *
+ * In Vue, `useAttrs()` is the fallthrough attributes NOT declared in `props`.
+ * `@pyreon/vue-compat` does not do declared-prop separation (components are
+ * plain functions receiving one `props` object), so this returns the full
+ * props object — every consumer-supplied attribute is present.
+ *
+ * LIMITATIONS vs Vue 3:
+ *  - No declared-vs-fallthrough split: `useAttrs()` here === the full props
+ *    object (including any that Vue would have consumed as declared props).
+ *    Read the specific keys you need; don't assume the result excludes
+ *    declared props.
+ *  - Returns an empty object when called outside a component.
+ *
+ * @example
+ * import { useAttrs } from "@pyreon/vue-compat"
+ *
+ * function Passthrough() {
+ *   const attrs = useAttrs()
+ *   return <input {...attrs} />
+ * }
+ */
+export function useAttrs(): Record<string, unknown> {
+  const ctx = getCurrentCtx()
+  if (!ctx) return {}
+  // Vue's `attrs` = fallthrough props (declared props excluded). The split is
+  // known when the component used `defineComponent({ props })`; otherwise the
+  // full props object is returned (honest — the split is unknowable).
+  return splitVueAttrs(ctx._props ?? {}, ctx._declaredProps)
 }
 
 // ─── watchPostEffect / watchSyncEffect ───────────────────────────────────────

package/src/jsx-runtime.ts

@@ -33,6 +33,19 @@ export interface RenderContext {
   unmounted: boolean
   /** Callbacks to run on unmount (lifecycle + effect cleanups) */
   unmountCallbacks: (() => void)[]
+  /**
+   * The props object the wrapped component was invoked with. Read by
+   * `getCurrentInstance()` / `useSlots()` / `useAttrs()` to derive slots
+   * + attrs. Set by the wrapper before each render.
+   */
+  _props?: Record<string, unknown>
+  /**
+   * Names of props declared via `defineComponent({ props })`. Set by
+   * `defineComponent` so `useAttrs()` / `getCurrentInstance().attrs` can
+   * compute the Vue declared-vs-fallthrough split. Undefined when the
+   * component didn't declare props (then attrs = the full props object).
+   */
+  _declaredProps?: string[]
 }
 
 export interface EffectEntry {
@@ -106,6 +119,7 @@ function wrapCompatComponent(vueComponent: Function): ComponentFn {
       pendingLayoutEffects: [],
       unmounted: false,
       unmountCallbacks: [],
+      _props: props as Record<string, unknown>,
     }
 
     const version = signal(0)