@pyreon/kinetic 0.21.0 → 0.23.0

package/src/__tests__/top-level-transition-stagger-function-children.test.tsx

@@ -0,0 +1,141 @@
+/** @jsxImportSource @pyreon/core */
+/**
+ * Regression: PR #731 fixed the kinetic-mode renderers (StaggerRenderer +
+ * TransitionItem under `src/kinetic/`) but missed the parallel TOP-LEVEL
+ * `<Transition>` and `<Stagger>` components in `src/Transition.tsx` and
+ * `src/Stagger.tsx`. They have the SAME iteration + cloneVNode shape and
+ * the SAME bug when the Pyreon compiler wraps the children prop in
+ * `() => x` (the prop-inlining pass).
+ *
+ * The Pyreon vite-plugin auto-wraps `<Comp>{x}</Comp>` JSX child
+ * expressions in `() => x` for stable prop-derived references; downstream
+ * libraries that iterate `props.children` directly at the VNode level or
+ * `cloneVNode` them silently break — the function spread produces
+ * `{type: undefined}` → `<undefined>` DOM tags. PR #732 added the
+ * compiler carve-out for stable references; library-side `resolveChildren`
+ * is still needed for the CallExpression-inside-JSX-child shape that the
+ * compiler (correctly) doesn't optimize.
+ *
+ * Bisect-verified: reverting the `resolveChildren` call in `Stagger.tsx`
+ * fails the Stagger spec (no children rendered); reverting in
+ * `Transition.tsx` fails the Transition spec (`<undefined>` tag rendered
+ * instead of the cloned child).
+ */
+import type { VNode } from '@pyreon/core'
+import { h } from '@pyreon/core'
+import { mount } from '@pyreon/runtime-dom'
+import { afterEach, describe, expect, it } from 'vitest'
+import Stagger from '../Stagger'
+import Transition from '../Transition'
+
+let containers: HTMLElement[] = []
+afterEach(() => {
+  for (const c of containers) c.remove()
+  containers = []
+})
+
+describe('top-level <Stagger> — function-wrapped children survive render', () => {
+  it('iterates function-wrapped children correctly (no empty render)', () => {
+    const childArray: VNode[] = [
+      h('h1', { 'data-id': 'st-h1' }, 'Hello'),
+      h('p', { 'data-id': 'st-p' }, 'tagline'),
+      h('ul', { 'data-id': 'st-ul' }, h('li', null, 'a')),
+    ]
+
+    const tree = h(Stagger, {
+      show: () => true,
+      appear: true,
+      interval: 20,
+      // Compiler-emitted shape: children is a function returning the array.
+      children: (() => childArray) as unknown as VNode[],
+    })
+
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+    containers.push(container)
+
+    const dispose = mount(tree as VNode, container)
+
+    const h1 = container.querySelector('[data-id="st-h1"]')
+    const p = container.querySelector('[data-id="st-p"]')
+    const ul = container.querySelector('[data-id="st-ul"]')
+
+    expect(
+      h1,
+      `Stagger collapsed when children is a function — html=${container.innerHTML.slice(0, 400)}`,
+    ).not.toBeNull()
+    expect(h1?.tagName).toBe('H1')
+    expect(h1?.textContent).toBe('Hello')
+    expect(p?.tagName).toBe('P')
+    expect(ul?.tagName).toBe('UL')
+    expect(container.querySelector('undefined')).toBeNull()
+
+    dispose()
+  })
+
+  it('static-array children control — was always working', () => {
+    const tree = h(
+      Stagger,
+      { show: () => true, appear: true, interval: 20 },
+      h('h1', { 'data-id': 'st-static' }, 'Static'),
+      h('p', { 'data-id': 'st-static-p' }, 't'),
+    )
+
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+    containers.push(container)
+    const dispose = mount(tree as VNode, container)
+
+    expect(container.querySelector('[data-id="st-static"]')?.tagName).toBe('H1')
+    expect(container.querySelector('[data-id="st-static-p"]')?.tagName).toBe('P')
+
+    dispose()
+  })
+})
+
+describe('top-level <Transition> — function-wrapped children survive render', () => {
+  it('resolves function-wrapped children before cloneVNode (no <undefined> tag)', () => {
+    const childVNode = h('h1', { 'data-id': 'tn-h1' }, 'Hello')
+
+    const tree = h(Transition, {
+      show: () => true,
+      appear: false,
+      // Compiler-emitted shape.
+      children: (() => childVNode) as unknown as VNode,
+    })
+
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+    containers.push(container)
+
+    const dispose = mount(tree as VNode, container)
+
+    const h1 = container.querySelector('[data-id="tn-h1"]')
+    expect(
+      h1,
+      `Transition produced <undefined> — html=${container.innerHTML.slice(0, 400)}`,
+    ).not.toBeNull()
+    expect(h1?.tagName).toBe('H1')
+    expect(h1?.textContent).toBe('Hello')
+    expect(container.querySelector('undefined')).toBeNull()
+
+    dispose()
+  })
+
+  it('static-VNode child control — was always working', () => {
+    const tree = h(
+      Transition,
+      { show: () => true, appear: false },
+      h('h1', { 'data-id': 'tn-static' }, 'Static'),
+    )
+
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+    containers.push(container)
+    const dispose = mount(tree as VNode, container)
+
+    expect(container.querySelector('[data-id="tn-static"]')?.tagName).toBe('H1')
+
+    dispose()
+  })
+})

package/src/kinetic/CollapseRenderer.tsx

@@ -166,6 +166,39 @@ const CollapseRenderer = ({
     ...(stage() === 'hidden' ? { height: '0px' } : stage() === 'entered' ? { height: 'auto' } : {}),
   }
 
+  // Initially-visible Collapses keep the original Show-gated inner content,
+  // preserving the runtime-unmount semantic that frees the inner subtree
+  // when the collapse is closed long-term. The SSR bug fires only when
+  // `show: () => false` at setup — the outer wrapper renders (with
+  // `height: 0; overflow: hidden`) but its children are stripped by the
+  // inner `<Show when={false}>` → empty wrapper in the prerendered HTML.
+  // Bad for SEO / social scrapers / accessibility / no-JS.
+  //
+  // Mirrors the fix shape applied to `<Transition>` (PR #717), the
+  // `TransitionRenderer` and `TransitionItem` (this PR). Ecosystem norm:
+  // content is structural, animation is visual.
+  //
+  // For initially-hidden Collapses, the inner content always renders —
+  // the outer wrapper's `height: 0px; overflow: hidden` already provides
+  // the visual hiding (genuinely layout-safe — no flex slot collapse;
+  // the outer wrapper participates in flex as a 0-height box, which is
+  // the standard CSS collapse behavior). When `show` flips true, the
+  // existing `watch(stage)` measures `content.scrollHeight` and animates
+  // height from 0 → that value — no change to the animation path.
+  //
+  // Trade-off: for initially-hidden Collapses, the inner subtree is
+  // ALWAYS mounted (never unmounted after a later close). Initially-
+  // visible Collapses keep the unmount behavior. Matches the trade-off
+  // documented across the other three kinetic renderers.
+  const wasInitiallyShown = show()
+  const innerContent = wasInitiallyShown ? (
+    <Show when={shouldRender}>
+      <div ref={contentRef}>{children}</div>
+    </Show>
+  ) : (
+    <div ref={contentRef}>{children}</div>
+  )
+
   // mergeProps (descriptor-preserving) instead of `{ ...htmlProps }` —
   // every non-style HTML attr keeps its reactive getter; ref + the
   // collapse-controlled style come last so they win (mergeProps is
@@ -176,9 +209,7 @@ const CollapseRenderer = ({
   return h(
     config.tag,
     mergeProps(htmlProps, { ref: wrapperRef, style: wrapperStyle }),
-    <Show when={shouldRender}>
-      <div ref={contentRef}>{children}</div>
-    </Show>,
+    innerContent,
   )
 }
 

package/src/kinetic/StaggerRenderer.tsx

@@ -1,7 +1,7 @@
 import type { VNode } from '@pyreon/core'
 import { h } from '@pyreon/core'
 import type { CSSProperties, TransitionCallbacks } from '../types'
-import { cloneVNode } from '../utils'
+import { cloneVNode, resolveChildren } from '../utils'
 import TransitionItem from './TransitionItem'
 import type { KineticConfig } from './types'
 
@@ -41,7 +41,9 @@ const StaggerRenderer = ({
   const effectiveInterval = interval ?? config.interval ?? 50
   const effectiveReverseLeave = reverseLeave ?? config.reverseLeave ?? false
 
-  const childArray = (Array.isArray(children) ? children : [children]).filter(isVNode)
+  // Unwrap compiler-emitted accessor wrap — see `resolveChildren` jsdoc.
+  const resolved = resolveChildren(children)
+  const childArray = (Array.isArray(resolved) ? resolved : [resolved]).filter(isVNode)
   const count = childArray.length
 
   const staggeredChildren = childArray.map((child, index) => {

package/src/kinetic/TransitionItem.tsx

@@ -1,11 +1,19 @@
 import type { VNode } from '@pyreon/core'
-import { createRef, Show } from '@pyreon/core'
+import { createRef, cx, Show } from '@pyreon/core'
 import { watch } from '@pyreon/reactivity'
 import type { ClassTransitionProps, StyleTransitionProps, TransitionCallbacks } from '../types'
 import useAnimationEnd from '../useAnimationEnd'
 import { useReducedMotion } from '../useReducedMotion'
 import useTransitionState from '../useTransitionState'
-import { addClasses, cloneVNode, mergeRefs, mergeStyles, nextFrame, removeClasses } from '../utils'
+import {
+  addClasses,
+  cloneVNode,
+  mergeRefs,
+  mergeStyles,
+  nextFrame,
+  removeClasses,
+  resolveChildren,
+} from '../utils'
 
 type TransitionItemProps = ClassTransitionProps &
   StyleTransitionProps &
@@ -19,6 +27,14 @@ type TransitionItemProps = ClassTransitionProps &
   }
 
 const applyEnter = (el: HTMLElement, config: ClassTransitionProps & StyleTransitionProps) => {
+  // Symmetric to applyLeave: clear residual leave-cycle classes — including
+  // the `leaveTo`/`enterFrom` class the SSR/initially-hidden render path
+  // inlines (see the `wasInitiallyShown` branch below). Without this, the
+  // SSR-baked hidden class would compete with `enterTo`'s CSS rules.
+  removeClasses(el, config.leave)
+  removeClasses(el, config.leaveFrom)
+  removeClasses(el, config.leaveTo)
+
   addClasses(el, config.enter)
   addClasses(el, config.enterFrom)
   if (config.enterStyle) Object.assign(el.style, config.enterStyle)
@@ -70,6 +86,18 @@ const applyReducedMotion = (
  * Uses cloneVNode to inject ref onto the child — the child must accept ref.
  */
 const TransitionItem = (props: TransitionItemProps): VNode | null => {
+  // The Pyreon compiler wraps `{cloneVNode(child, {...})}` JSX child
+  // expressions in StaggerRenderer/GroupRenderer as `() => cloneVNode(...)`
+  // (prop-inlining for reactivity — see `resolveChildren` jsdoc). At this
+  // boundary `props.children` therefore arrives as a FUNCTION instead of a
+  // VNode. cloneVNode-on-a-function silently produces `{type: undefined,
+  // props: {ref: ...}}` (spreading a function yields no own properties
+  // because functions have none enumerable), which mountElement renders
+  // as a literal `<undefined>` tag in the DOM — the SSG'd `<h1>Hello</h1>`
+  // becomes an empty `<undefined></undefined>` post-hydrate (reproducer:
+  // bokisch.com Intro section). Resolve eagerly so the entire body below
+  // can treat `child` as a static VNode.
+  const child = resolveChildren(props.children) as VNode
   const appear = props.appear ?? false
   const unmount = props.unmount ?? true
   const timeout = props.timeout ?? 5000
@@ -83,7 +111,7 @@ const TransitionItem = (props: TransitionItemProps): VNode | null => {
   const mergedRef = mergeRefs(
     elementRef,
     stateRef,
-    (props.children.props as Record<string, unknown>)?.ref as
+    (child?.props as Record<string, unknown>)?.ref as
       | ((el: HTMLElement | null) => void)
       | undefined,
   )
@@ -155,26 +183,68 @@ const TransitionItem = (props: TransitionItemProps): VNode | null => {
     { immediate: true },
   )
 
-  return (
-    <Show
-      when={shouldMount}
-      fallback={
-        unmount
-          ? null
-          : cloneVNode(props.children, {
-              ref: mergedRef,
-              style: mergeStyles(
-                (props.children.props as Record<string, unknown>)?.style as
-                  | Record<string, string | number | undefined>
-                  | undefined,
-                { display: 'none' },
-              ),
-            })
-      }
-    >
-      {cloneVNode(props.children, { ref: mergedRef })}
-    </Show>
+  // Initially-visible items keep the original Show-gated mount, preserving
+  // the documented runtime-unmount semantic for visible→hidden. The SSR
+  // bug (children dropped from prerendered HTML) only fires for the
+  // initially-HIDDEN case below, where `<Show when={false}>` renders `null`
+  // on the server. For Stagger/Group usage at SSR (when the parent's
+  // `show: () => false`), each per-item TransitionItem hit this and
+  // dropped its child — full list missing from prerendered HTML.
+  //
+  // Mirrors the fix in `<Transition>` (PR #717) and `TransitionRenderer`
+  // (same PR as this). Ecosystem norm: content is structural, animation
+  // is visual.
+  const wasInitiallyShown = props.show()
+  if (wasInitiallyShown) {
+    return (
+      <Show
+        when={shouldMount}
+        fallback={
+          unmount
+            ? null
+            : cloneVNode(child, {
+                ref: mergedRef,
+                style: mergeStyles(
+                  (child?.props as Record<string, unknown>)?.style as
+                    | Record<string, string | number | undefined>
+                    | undefined,
+                  { display: 'none' },
+                ),
+              })
+        }
+      >
+        {cloneVNode(child, { ref: mergedRef })}
+      </Show>
+    )
+  }
+
+  // Initially-hidden path — always emit the child with hidden-state class +
+  // style inlined. `leaveTo`/`leaveToStyle` (explicit hidden-end state)
+  // wins; falls back to `enterFrom`/`enterStyle` (pre-enter state — covers
+  // both class-based scroll-reveal AND the preset path, where
+  // `@pyreon/kinetic-presets` factories populate `enterStyle` as the
+  // hidden state but may not set `leaveToStyle`).
+  //
+  // Trade-off: for an initially-hidden item, `unmount: true` no longer
+  // triggers a true DOM removal after a later leave animation completes.
+  // Initially-visible items keep the unmount semantic.
+  const hiddenClass = props.leaveTo ?? props.enterFrom
+  const hiddenStyle = props.leaveToStyle ?? props.enterStyle
+  const childProps = (child?.props ?? {}) as Record<string, unknown>
+  const childClass = childProps.class
+  const mergedClass = hiddenClass
+    ? cx([childClass as Parameters<typeof cx>[0], hiddenClass])
+    : undefined
+  const mergedStyle = mergeStyles(
+    childProps.style as Record<string, string | number | undefined> | undefined,
+    hiddenStyle,
   )
+
+  const extra: Record<string, unknown> = { ref: mergedRef }
+  if (mergedClass !== undefined) extra.class = mergedClass
+  if (mergedStyle !== undefined) extra.style = mergedStyle
+
+  return cloneVNode(child, extra)
 }
 
 export default TransitionItem

package/src/kinetic/TransitionRenderer.tsx

@@ -1,5 +1,5 @@
 import type { VNode } from '@pyreon/core'
-import { createRef, h, mergeProps, Show } from '@pyreon/core'
+import { createRef, cx, h, mergeProps, Show } from '@pyreon/core'
 import { watch } from '@pyreon/reactivity'
 import type { CSSProperties, TransitionCallbacks } from '../types'
 import useAnimationEnd from '../useAnimationEnd'
@@ -20,6 +20,15 @@ type TransitionRendererProps = {
 }
 
 const applyEnter = (el: HTMLElement, config: KineticConfig) => {
+  // Symmetric to applyLeave's `removeClasses(enter)` / `removeClasses(enterTo)`:
+  // clear residual leave-cycle classes — including the `leaveTo` / `enterFrom`
+  // class the SSR / initially-hidden render path inlines for structural
+  // content (see the `wasInitiallyShown` branch below). Without this, the
+  // SSR-baked hidden-state class would compete with `enterTo`'s CSS rules.
+  removeClasses(el, config.leave)
+  removeClasses(el, config.leaveFrom)
+  removeClasses(el, config.leaveTo)
+
   addClasses(el, config.enter)
   addClasses(el, config.enterFrom)
   if (config.enterStyle) Object.assign(el.style, config.enterStyle)
@@ -131,38 +140,91 @@ const TransitionRenderer = (props: TransitionRendererProps): VNode | null => {
     { immediate: true },
   )
 
-  return (
-    <Show
-      when={shouldMount}
-      fallback={
-        effectiveUnmount
-          ? null
-          : h(
-              props.config.tag,
-              // mergeProps keeps every reactive HTML-attr getter; ref + the
-              // hidden-state `display:none` style come last and win. The
-              // one-time `props.htmlProps.style` read seeds the hidden
-              // style — display:none must compose over the user's style.
-              mergeProps(props.htmlProps, {
-                ref: mergedRef,
-                style: {
-                  ...((props.htmlProps.style as CSSProperties) ?? {}),
-                  display: 'none',
-                },
-              }),
-              props.children,
-            )
-      }
-    >
-      {h(
-        props.config.tag,
-        // Descriptor-preserving merge — reactive HTML attrs keep their
-        // getters; ref wins last. `{ ...props.htmlProps }` would freeze them.
-        mergeProps(props.htmlProps, { ref: mergedRef }),
-        props.children,
-      )}
-    </Show>
-  )
+  // Initially-visible kinetic-mode Transitions keep the original Show-gated
+  // mount, preserving the documented runtime-unmount semantic for the
+  // visible→hidden transition. The SSR bug (children dropped from prerendered
+  // HTML) only fires for the initially-HIDDEN case below, where
+  // `<Show when={false}>` renders `null` on the server — leaving SSG sites
+  // using kinetic-mode transitions (e.g. `kinetic('div').preset(fadeUp)` with
+  // `show: () => false` at SSR, the scroll-reveal pattern via
+  // `useIntersection`) without structural content for SEO / social scrapers
+  // / accessibility tools / no-JS users.
+  //
+  // Mirrors the same fix shape applied to the top-level `<Transition>` in
+  // PR #717. Ecosystem norm (Framer Motion / react-transition-group / react-
+  // spring): content is structural, animation is visual.
+  const wasInitiallyShown = props.show()
+  if (wasInitiallyShown) {
+    return (
+      <Show
+        when={shouldMount}
+        fallback={
+          effectiveUnmount
+            ? null
+            : h(
+                props.config.tag,
+                // mergeProps keeps every reactive HTML-attr getter; ref + the
+                // hidden-state `display:none` style come last and win. The
+                // one-time `props.htmlProps.style` read seeds the hidden
+                // style — display:none must compose over the user's style.
+                mergeProps(props.htmlProps, {
+                  ref: mergedRef,
+                  style: {
+                    ...((props.htmlProps.style as CSSProperties) ?? {}),
+                    display: 'none',
+                  },
+                }),
+                props.children,
+              )
+        }
+      >
+        {h(
+          props.config.tag,
+          // Descriptor-preserving merge — reactive HTML attrs keep their
+          // getters; ref wins last. `{ ...props.htmlProps }` would freeze them.
+          mergeProps(props.htmlProps, { ref: mergedRef }),
+          props.children,
+        )}
+      </Show>
+    )
+  }
+
+  // Initially-hidden path — ecosystem-correct: always emit children with
+  // hidden-state class/style inlined so SSG / SEO / social scrapers / no-JS
+  // users see structural content. `leaveTo` (explicit hidden-end state)
+  // wins; falls back to `enterFrom` (pre-enter state) for scroll-reveal
+  // patterns that only configure the enter side. The existing
+  // `watch(stage)` effect drives the enter animation when `show` flips
+  // true; the symmetric `applyEnter` above clears these residual classes.
+  //
+  // Trade-off: for initially-hidden kinetic-mode Transitions, `unmount: true`
+  // no longer triggers a true DOM removal after a later leave animation
+  // completes — element stays in DOM with the leave-to class applied.
+  // Initially-visible Transitions (the branch above) keep the unmount
+  // semantic. Matches Framer Motion / react-transition-group conventions
+  // and is the price of SSR correctness.
+  // Mirrors the class picker: prefer `leaveTo`/`leaveToStyle` (explicit
+  // leave-end / hidden state) and fall back to `enterFrom`/`enterStyle`
+  // (pre-enter state). The fallback covers the preset path —
+  // `@pyreon/kinetic-presets` factories (fadeUp, slideLeft, blurInUp, …)
+  // populate `enterStyle` as the hidden state and may not set
+  // `leaveToStyle` at all; without this fallback, presets would SSR-render
+  // VISIBLE → flash-on-hydration.
+  const hiddenClass = props.config.leaveTo ?? props.config.enterFrom
+  const hiddenStyle = props.config.leaveToStyle ?? props.config.enterStyle
+  const childClass = props.htmlProps.class
+  const mergedClass = hiddenClass
+    ? cx([childClass as Parameters<typeof cx>[0], hiddenClass])
+    : undefined
+  const mergedStyle = hiddenStyle
+    ? { ...((props.htmlProps.style as CSSProperties) ?? {}), ...hiddenStyle }
+    : undefined
+
+  const extra: Record<string, unknown> = { ref: mergedRef }
+  if (mergedClass !== undefined) extra.class = mergedClass
+  if (mergedStyle !== undefined) extra.style = mergedStyle
+
+  return h(props.config.tag, mergeProps(props.htmlProps, extra), props.children)
 }
 
 export default TransitionRenderer

package/src/utils.ts

@@ -83,3 +83,31 @@ export const cloneVNode = (vnode: VNode, extraProps: Record<string, unknown>): V
   ...vnode,
   props: { ...vnode.props, ...extraProps },
 })
+
+/**
+ * Resolves a `children` value the Pyreon compiler may have wrapped in a
+ * deferred accessor.
+ *
+ * **Why:** the compiler's prop-inlining pass rewrites `<Comp>{children}</Comp>`
+ * to `Comp({ ..., children: () => <inlined-expression> })` whenever
+ * `children` is a local `const` derived from a getter-shaped binding
+ * (`const children = childHolder.children` after `splitProps`). DOM-side
+ * consumers route through `mountChild` which already treats function
+ * children as reactive accessors, so the wrap is invisible there. Kinetic's
+ * Stagger/Group/Transition/Collapse renderers iterate `children` directly
+ * at the VNode level (to build per-child `TransitionItem`s), so a wrapped
+ * function landed in `Array.isArray(children) ? children : [children]` as
+ * `[function]` → `.filter(isVNode)` → `[]` → the rendered `<div>` had zero
+ * children → SSR content vanished post-hydration. Reproducer:
+ * `examples/bokisch.com`'s Intro section with `kinetic('div').stagger()`
+ * + `appear` + `show={() => true}` + component children → SSG HTML had
+ * `<h1>Hello</h1>`, post-hydrate the entire subtree was replaced by
+ * `<!--pyreon-->` markers.
+ *
+ * Kinetic deliberately snapshots children at render time (animation state
+ * is per-item, built once) — it does NOT observe children changes after
+ * the initial render. Eagerly unwrapping the function matches that
+ * contract; no reactivity is lost.
+ */
+export const resolveChildren = <T>(children: T | (() => T)): T =>
+  (typeof children === 'function' ? (children as () => T)() : children) as T