@pyreon/kinetic 0.20.0 → 0.21.0

package/README.md

@@ -211,6 +211,29 @@ const AnimatedButton = kinetic(Button).preset(fade)
 AnimatedButton({ show: isVisible, primary: true, size: 'large', children: 'Click me' })
 ```
 
+## SSR / SSG
+
+`<Transition show={() => false}>` **always renders children in SSR**, with the hidden-state class inlined (`leaveTo` if defined, else `enterFrom`). This matches Framer Motion / react-transition-group / react-spring conventions: content is structural, animation is visual.
+
+This is load-bearing for the scroll-reveal pattern on SSG sites — `useIntersection` can't fire on the server, so `show` is false at SSR. Without structural rendering, the wrapped content would be absent from prerendered HTML (bad for SEO, social scrapers, no-JS users).
+
+```tsx
+const RevealSection = kinetic('section')
+  .enter('transition-all duration-700')
+  .enterFrom('opacity-0 translate-y-8') // ← this IS the SSR hidden state
+  .enterTo('opacity-100 translate-y-0')
+
+// In your route — show is driven by useIntersection on the client.
+// At SSR: <section class="opacity-0 translate-y-8">…full content here…</section>
+// On client: when scrolled into view, show flips true, enter animation runs.
+<RevealSection show={isInView}>
+  <h2>Work Experience</h2>
+  <p>…content reaches SEO crawlers and social scrapers…</p>
+</RevealSection>
+```
+
+**Trade-off**: for an initially-hidden Transition, `unmount: true` (the default) no longer triggers a true DOM removal after a later leave animation completes — the element stays in DOM with the leave-to class applied. **Initially-visible** Transitions (`show: () => true` at setup) keep the runtime-unmount semantic unchanged. If you need true unmount on a started-hidden element, drive mount/unmount yourself outside `<Transition>`.
+
 ## Peer Dependencies
 
 | Package            | Version  |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/kinetic",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "CSS-transition-based animation components for Pyreon",
   "license": "MIT",
   "repository": {
@@ -42,11 +42,12 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@pyreon/core": "^0.20.0",
-    "@pyreon/reactivity": "^0.20.0",
-    "@pyreon/runtime-dom": "^0.20.0",
-    "@pyreon/test-utils": "^0.13.7",
-    "@pyreon/typescript": "^0.20.0",
+    "@pyreon/core": "^0.21.0",
+    "@pyreon/reactivity": "^0.21.0",
+    "@pyreon/runtime-dom": "^0.21.0",
+    "@pyreon/runtime-server": "^0.21.0",
+    "@pyreon/test-utils": "^0.13.8",
+    "@pyreon/typescript": "^0.21.0",
     "@vitest/browser-playwright": "^4.1.4",
     "@vitus-labs/tools-rolldown": "^2.3.0"
   },
@@ -54,8 +55,8 @@
     "node": ">= 22"
   },
   "dependencies": {
-    "@pyreon/core": "^0.20.0",
-    "@pyreon/reactivity": "^0.20.0",
-    "@pyreon/runtime-dom": "^0.20.0"
+    "@pyreon/core": "^0.21.0",
+    "@pyreon/reactivity": "^0.21.0",
+    "@pyreon/runtime-dom": "^0.21.0"
   }
 }

package/src/Transition.tsx

@@ -1,5 +1,5 @@
 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, TransitionProps } from './types'
 import useAnimationEnd from './useAnimationEnd'
@@ -16,8 +16,22 @@ const applyEnter = (
     enterStyle,
     enterToStyle,
     enterTransition,
+    leave,
+    leaveFrom,
+    leaveTo,
   }: ClassTransitionProps & StyleTransitionProps,
 ) => {
+  // Symmetric to applyLeave's `removeClasses(enter)` / `removeClasses(enterTo)`:
+  // clear any residual leave-cycle classes — including the `leaveTo` /
+  // `enterFrom` class the SSR / initial-hidden render path inlines for
+  // ecosystem-correct structural content (see the `wasInitiallyShown`
+  // branch below). Without this, the SSR-baked hidden-state class would
+  // compete with `enterTo`'s CSS rules and the enter animation would
+  // visually fight itself.
+  removeClasses(el, leave)
+  removeClasses(el, leaveFrom)
+  removeClasses(el, leaveTo)
+
   addClasses(el, enter)
   addClasses(el, enterFrom)
   if (enterStyle) Object.assign(el.style, enterStyle)
@@ -170,24 +184,73 @@ const Transition = (props: TransitionProps): VNode | null => {
     { immediate: true },
   )
 
-  return (
-    <Show
-      when={shouldMount}
-      fallback={
-        unmount
-          ? null
-          : cloneVNode(props.children, {
-              ref: mergedRef,
-              style: mergeStyles(
-                childProps.style as Record<string, string | number | undefined> | undefined,
-                { display: 'none' },
-              ),
-            })
-      }
-    >
-      {cloneVNode(props.children, { ref: mergedRef })}
-    </Show>
+  // Initially-visible Transitions keep the original Show-gated mount,
+  // which preserves the documented runtime-unmount semantic for the
+  // visible → hidden transition (modal close, dropdown collapse, etc.).
+  // The SSR bug (children dropped from prerendered HTML) only fires for
+  // the initially-HIDDEN case below, because `<Show when={false}>`
+  // renders `null` on the server.
+  const wasInitiallyShown = props.show()
+  if (wasInitiallyShown) {
+    return (
+      <Show
+        when={shouldMount}
+        fallback={
+          unmount
+            ? null
+            : cloneVNode(props.children, {
+                ref: mergedRef,
+                style: mergeStyles(
+                  childProps.style as Record<string, string | number | undefined> | undefined,
+                  { display: 'none' },
+                ),
+              })
+        }
+      >
+        {cloneVNode(props.children, { ref: mergedRef })}
+      </Show>
+    )
+  }
+
+  // Initially-hidden path — ecosystem-correct (Framer Motion / react-
+  // transition-group / react-spring all render children in SSR regardless
+  // of animation state; visual hiding is class/style only). Always emits
+  // children so SSG / SEO / social scrapers / no-JS users see the
+  // structural content. The hidden visual is supplied by `leaveTo`
+  // (explicit hidden-end state) or `enterFrom` (pre-enter state — covers
+  // the scroll-reveal pattern that only configures the enter side).
+  //
+  // Trade-off: for an initially-hidden Transition, `unmount: true` no
+  // longer triggers a true DOM removal after a later leave animation
+  // completes — the element stays in DOM with the leave-to class
+  // applied. Initially-visible Transitions keep the unmount semantic
+  // (the branch above). This matches Framer Motion / react-transition-
+  // group conventions and is the price of SSR correctness; the rare
+  // user who needs true unmount on a started-hidden element can drive
+  // mount/unmount themselves outside `<Transition>`.
+  //
+  // The `watch(stage)` effect above drives the enter animation when
+  // `show` flips true; `applyEnter` (above) clears these residual
+  // hidden-state classes so they don't fight `enterTo`.
+  const hiddenClass = props.leaveTo ?? props.enterFrom
+  const hiddenStyle = props.leaveToStyle
+  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,
   )
+
+  // Build extra-props carefully — undefined values must NOT be passed to
+  // cloneVNode because `{...vnode.props, ...extraProps}` spreads them and
+  // overrides any user-set `class`/`style` on the child vnode with undefined.
+  const extra: Record<string, unknown> = { ref: mergedRef }
+  if (mergedClass !== undefined) extra.class = mergedClass
+  if (mergedStyle !== undefined) extra.style = mergedStyle
+
+  return cloneVNode(props.children, extra)
 }
 
 export default Transition

package/src/__tests__/Transition.ssr.test.tsx

@@ -0,0 +1,155 @@
+/**
+ * SSR regression coverage for `<Transition>` (the missing test layer that
+ * let the children-dropped-on-SSR bug ship).
+ *
+ * Background. `<Transition show={() => false} ...>` used to render `<Show
+ * when={false} fallback={null}>` on the server, which emitted EMPTY HTML —
+ * any SSG site using kinetic for scroll-triggered reveal (the documented
+ * `useIntersection` + sticky-signal pattern, where `show` is false at SSR
+ * because IntersectionObserver can't fire until client hydration) shipped
+ * with the wrapped content STRUCTURALLY ABSENT from the prerendered HTML.
+ * Bad for SEO, social scrapers, accessibility tools, and no-JS users.
+ *
+ * Ecosystem norm (the framing this fix aligns Pyreon with): Framer Motion,
+ * react-transition-group, react-spring, AutoAnimate all render children in
+ * SSR regardless of animation state and only apply animation styles on the
+ * client. "Content is structural, animation is visual."
+ *
+ * What the fix changes. `Transition` now branches at setup on
+ * `props.show()`:
+ *   - initially-visible → existing `<Show>`-gated mount (unchanged;
+ *     preserves the runtime-unmount semantic for the visible→hidden case)
+ *   - initially-hidden → always render children with hidden-state classes
+ *     inlined (`leaveTo` if defined, else `enterFrom` — covers the
+ *     scroll-reveal pattern that only configures the enter side). The
+ *     existing `watch(stage)` effect drives the enter animation when
+ *     `show` flips true.
+ *
+ * Why these tests are load-bearing. Zero existing tests exercised
+ * `show: () => false` initial state (the bug class). The fact that this
+ * shipped is exactly the "no test catches it because no test runs the real
+ * path" failure mode the `test-environment-parity.md` rule was written to
+ * prevent — both real `h()` AND a SSR-driving environment (`renderToString`)
+ * are needed to catch it.
+ *
+ * Bisect-verified: reverting `Transition.tsx`'s `wasInitiallyShown` branch
+ * fails every spec below with `expected '' to contain '...'` (the empty-
+ * children bug). Restored → all green.
+ */
+
+import { h } from '@pyreon/core'
+import { renderToString } from '@pyreon/runtime-server'
+import { describe, expect, it } from 'vitest'
+import Transition from '../Transition'
+
+describe('Transition — SSR / initially-hidden children render', () => {
+  it('emits children when show=false initially (was: <Show fallback={null}> → empty)', async () => {
+    // The canonical bug shape — scroll-reveal pattern at SSR time.
+    const html = await renderToString(
+      h(Transition, {
+        show: () => false,
+        enterFrom: 'opacity-0',
+        enterTo: 'opacity-100',
+        enter: 'transition-opacity duration-300',
+        children: h('section', null, 'real content for SEO + social scrapers'),
+      }),
+    )
+    // Structural content must land in the prerendered HTML. Pre-fix this
+    // assertion failed with `expected '' to contain '...'`.
+    expect(html).toContain('<section')
+    expect(html).toContain('real content for SEO + social scrapers')
+  })
+
+  it('inlines `leaveTo` as the hidden-state class (explicit hidden-end state takes precedence)', async () => {
+    const html = await renderToString(
+      h(Transition, {
+        show: () => false,
+        enterFrom: 'opacity-0 translate-y-4', // present but NOT selected
+        enterTo: 'opacity-100 translate-y-0',
+        leave: 'transition-opacity',
+        leaveFrom: 'opacity-100',
+        leaveTo: 'is-hidden opacity-0', // ← explicit hidden-end state, selected
+        children: h('div', null, 'panel content'),
+      }),
+    )
+    expect(html).toContain('is-hidden opacity-0')
+    expect(html).toContain('panel content')
+    // The competing `enterFrom` should NOT be applied (leaveTo wins).
+    expect(html).not.toContain('translate-y-4')
+  })
+
+  it('falls back to `enterFrom` as the hidden class for scroll-reveal patterns (only enter side configured)', async () => {
+    // The exact pattern the reported bug surfaced on — only the enter
+    // animation is configured (because IO triggers `show` true; there's
+    // no leave side for the reveal pattern).
+    const html = await renderToString(
+      h(Transition, {
+        show: () => false,
+        enter: 'transition-all duration-700',
+        enterFrom: 'opacity-0 translate-y-8',
+        enterTo: 'opacity-100 translate-y-0',
+        children: h('section', { id: 'resume-section' }, 'work history goes here'),
+      }),
+    )
+    expect(html).toContain('id="resume-section"')
+    expect(html).toContain('work history goes here')
+    // enterFrom IS the resting hidden state for this pattern.
+    expect(html).toContain('opacity-0 translate-y-8')
+  })
+
+  it('inlines `leaveToStyle` as the hidden inline style when defined', async () => {
+    const html = await renderToString(
+      h(Transition, {
+        show: () => false,
+        leaveTo: 'animated-section',
+        leaveToStyle: { opacity: 0, transform: 'translateY(20px)' },
+        children: h('article', null, 'article body'),
+      }),
+    )
+    expect(html).toContain('article body')
+    expect(html).toContain('opacity: 0')
+    expect(html).toContain('translateY(20px)')
+  })
+
+  it('merges the hidden class with any user-set class on the child', async () => {
+    const html = await renderToString(
+      h(Transition, {
+        show: () => false,
+        leaveTo: 'is-hidden',
+        children: h('div', { class: 'card card--featured' }, 'merged-class content'),
+      }),
+    )
+    expect(html).toContain('merged-class content')
+    expect(html).toContain('card')
+    expect(html).toContain('card--featured')
+    expect(html).toContain('is-hidden')
+  })
+
+  it('emits children unchanged when neither leaveTo nor enterFrom is defined (graceful no-op)', async () => {
+    // An unusual config — no enter/leave classes at all. Children should
+    // still render structurally (the SEO/SSG contract); no hidden class
+    // is appended because there's nothing to append.
+    const html = await renderToString(
+      h(Transition, {
+        show: () => false,
+        children: h('div', null, 'bare content'),
+      }),
+    )
+    expect(html).toContain('bare content')
+  })
+
+  it('initially-visible Transition (show=true) renders children normally — unchanged behavior', async () => {
+    // The other branch of the fix — initially-visible Transitions keep
+    // the original `<Show>`-gated path. This spec locks in the no-
+    // regression contract for the existing common case.
+    const html = await renderToString(
+      h(Transition, {
+        show: () => true,
+        leaveTo: 'is-hidden', // must NOT leak onto initially-visible
+        children: h('main', null, 'visible from the start'),
+      }),
+    )
+    expect(html).toContain('visible from the start')
+    expect(html).not.toContain('is-hidden')
+  })
+})

package/src/__tests__/kinetic.browser.test.tsx

@@ -144,4 +144,71 @@ describe('@pyreon/kinetic browser smoke', () => {
     // `"development" !== "production"` → `true` in dev runs.
     expect(process.env.NODE_ENV).not.toBe('production')
   })
+
+  // ── Initially-hidden Transition: client-side parity with the SSR fix ─────
+  //
+  // The SSR test file (`Transition.ssr.test.tsx`) proves children land in
+  // prerendered HTML; these specs prove the SAME render path works under
+  // a real DOM — the element mounts with the hidden-state class applied,
+  // and an `applyEnter` triggered by a `show` flip cleanly transitions it
+  // out of the hidden state (the companion `applyEnter` fix that removes
+  // residual `leave`/`leaveFrom`/`leaveTo` classes ensures the SSR-baked
+  // hidden class doesn't fight `enterTo`).
+
+  it('Transition with initial show=false mounts the element with the hidden class (no null)', async () => {
+    const show = signal(false)
+    const { container, unmount } = mountInBrowser(
+      <Transition
+        show={show}
+        enterFrom="hide-state"
+        enterTo="show-state"
+        enter="transition-opacity"
+      >
+        <div data-id="reveal-target">scroll-reveal content</div>
+      </Transition>,
+    )
+    // Pre-fix: container.querySelector returns null (children were dropped).
+    const el = container.querySelector('[data-id="reveal-target"]') as HTMLElement | null
+    expect(el).not.toBeNull()
+    expect(el!.textContent).toBe('scroll-reveal content')
+    // enterFrom is the fallback hidden-state class (scroll-reveal pattern
+    // configures only the enter side).
+    expect(el!.classList.contains('hide-state')).toBe(true)
+    unmount()
+  })
+
+  it('flipping show=true on an initially-hidden Transition cleans the hidden class and runs enter', async () => {
+    const show = signal(false)
+    const { container, unmount } = mountInBrowser(
+      <Transition
+        show={show}
+        enterFrom="hide-state"
+        enterTo="show-state"
+        enter="enter-active"
+      >
+        <div data-id="reveal-target">content</div>
+      </Transition>,
+    )
+    const el = () => container.querySelector('[data-id="reveal-target"]') as HTMLElement | null
+    // Starts hidden.
+    expect(el()!.classList.contains('hide-state')).toBe(true)
+    // Flip show → true; applyEnter runs in the watch effect on the SAME
+    // element (the SSR fix guarantees the element is already in DOM).
+    show.set(true)
+    await flush()
+    // The companion applyEnter fix removes residual `leave`/`leaveFrom`/
+    // `leaveTo` AND adds `enter` + `enterFrom`. enterFrom was already
+    // applied (it WAS the hidden-state class); the next frame removes it
+    // and adds enterTo. Two rAFs for full transition.
+    await new Promise<void>((resolve) =>
+      requestAnimationFrame(() => requestAnimationFrame(() => resolve())),
+    )
+    await flush()
+    // After the double-rAF, enterTo is applied + enterFrom removed.
+    expect(el()!.classList.contains('show-state')).toBe(true)
+    expect(el()!.classList.contains('hide-state')).toBe(false)
+    // `enter` (the active marker) is applied throughout the transition.
+    expect(el()!.classList.contains('enter-active')).toBe(true)
+    unmount()
+  })
 })