@pyreon/kinetic 0.11.0 → 0.11.2

package/src/kinetic/CollapseRenderer.tsx

@@ -0,0 +1,178 @@
+import type { VNode } from "@pyreon/core"
+import { createRef, h, Show } from "@pyreon/core"
+import { runUntracked, signal, watch } from "@pyreon/reactivity"
+import type { CSSProperties, TransitionCallbacks, TransitionStage } from "../types"
+import useAnimationEnd from "../useAnimationEnd"
+import { useReducedMotion } from "../useReducedMotion"
+import type { KineticConfig } from "./types"
+
+type CollapseRendererProps = {
+  config: KineticConfig
+  htmlProps: Record<string, unknown>
+  show: () => boolean
+  appear?: boolean | undefined
+  timeout?: number | undefined
+  transition?: string | undefined
+  callbacks: Partial<TransitionCallbacks>
+  children: VNode | VNode[]
+}
+
+/**
+ * Renders a height-animated collapse. The config.tag becomes the outer
+ * wrapper (overflow:hidden + animated height). An inner div measures
+ * scrollHeight for the target value.
+ */
+const CollapseRenderer = ({
+  config,
+  htmlProps,
+  show,
+  appear,
+  timeout,
+  transition,
+  callbacks,
+  children,
+}: CollapseRendererProps): VNode | null => {
+  const reducedMotion = useReducedMotion()
+  let wrapperRef: { current: HTMLElement | null } = createRef<HTMLElement>()
+  const contentRef = createRef<HTMLDivElement>()
+
+  const effectiveAppear = appear ?? config.appear ?? false
+  const effectiveTimeout = timeout ?? config.timeout ?? 5000
+  const effectiveTransition = transition ?? config.transition ?? "height 300ms ease"
+
+  const initialShow = show()
+  const needsAppear = effectiveAppear && initialShow
+  const stage = signal<TransitionStage>(initialShow ? "entered" : "hidden")
+  let isInitialMount = true
+  let appearTriggered = false
+
+  // Intercept ref assignment to trigger appear after all refs are wired
+  if (needsAppear) {
+    const orig = wrapperRef
+    const proxy = { current: null as HTMLElement | null }
+    Object.defineProperty(proxy, "current", {
+      get() {
+        return orig.current
+      },
+      set(node: HTMLElement | null) {
+        orig.current = node
+        if (node && !appearTriggered) {
+          appearTriggered = true
+          queueMicrotask(() => stage.set("entering"))
+        }
+      },
+    })
+    wrapperRef = proxy
+  }
+
+  // State machine transitions
+  watch(
+    show,
+    (showVal) => {
+      if (isInitialMount) {
+        isInitialMount = false
+        // appear case is handled by ref proxy above
+        return
+      }
+
+      const currentStage = runUntracked(() => stage())
+      if (showVal && (currentStage === "hidden" || currentStage === "leaving")) {
+        stage.set("entering")
+      } else if (!showVal && (currentStage === "entered" || currentStage === "entering")) {
+        stage.set("leaving")
+      }
+    },
+    { immediate: true },
+  )
+
+  // Animate height
+  watch(
+    () => stage(),
+    (currentStage) => {
+      const wrapper = wrapperRef.current
+      const content = contentRef.current
+      if (!wrapper || !content) return
+
+      if (reducedMotion()) {
+        if (currentStage === "entering") {
+          callbacks.onEnter?.()
+          wrapper.style.height = "auto"
+          wrapper.style.overflow = ""
+          callbacks.onAfterEnter?.()
+          stage.set("entered")
+        } else if (currentStage === "leaving") {
+          callbacks.onLeave?.()
+          wrapper.style.height = "0px"
+          wrapper.style.overflow = "hidden"
+          callbacks.onAfterLeave?.()
+          stage.set("hidden")
+        }
+        return
+      }
+
+      if (currentStage === "entering") {
+        callbacks.onEnter?.()
+        const height = content.scrollHeight
+        wrapper.style.transition = "none"
+        wrapper.style.height = "0px"
+        wrapper.style.overflow = "hidden"
+        // Force reflow
+        void wrapper.offsetHeight
+        wrapper.style.transition = effectiveTransition
+        wrapper.style.height = `${height}px`
+      }
+
+      if (currentStage === "leaving") {
+        callbacks.onLeave?.()
+        const height = content.scrollHeight
+        wrapper.style.transition = "none"
+        wrapper.style.height = `${height}px`
+        wrapper.style.overflow = "hidden"
+        // Force reflow
+        void wrapper.offsetHeight
+        wrapper.style.transition = effectiveTransition
+        wrapper.style.height = "0px"
+      }
+    },
+    { immediate: true },
+  )
+
+  useAnimationEnd({
+    ref: wrapperRef,
+    active: () => (stage() === "entering" || stage() === "leaving") && !reducedMotion(),
+    timeout: effectiveTimeout,
+    onEnd: () => {
+      const wrapper = wrapperRef.current
+      if (stage() === "entering") {
+        if (wrapper) {
+          wrapper.style.height = "auto"
+          wrapper.style.overflow = ""
+          wrapper.style.transition = ""
+        }
+        callbacks.onAfterEnter?.()
+        stage.set("entered")
+      } else if (stage() === "leaving") {
+        callbacks.onAfterLeave?.()
+        stage.set("hidden")
+      }
+    },
+  })
+
+  const shouldRender = () => stage() !== "hidden"
+
+  const wrapperStyle: CSSProperties = {
+    ...((htmlProps.style as CSSProperties) ?? {}),
+    ...(stage() !== "entered" ? { overflow: "hidden" } : {}),
+    ...(stage() === "hidden" ? { height: "0px" } : stage() === "entered" ? { height: "auto" } : {}),
+  }
+
+  return h(
+    config.tag,
+    { ref: wrapperRef, ...htmlProps, style: wrapperStyle },
+    <Show when={shouldRender}>
+      <div ref={contentRef}>{children}</div>
+    </Show>,
+  )
+}
+
+export default CollapseRenderer

package/src/kinetic/GroupRenderer.tsx

@@ -0,0 +1,124 @@
+import type { VNode } from "@pyreon/core"
+import { h } from "@pyreon/core"
+import { signal } from "@pyreon/reactivity"
+import type { TransitionCallbacks } from "../types"
+import TransitionItem from "./TransitionItem"
+import type { KineticConfig } from "./types"
+
+type GroupRendererProps = {
+  config: KineticConfig
+  htmlProps: Record<string, unknown>
+  appear?: boolean | undefined
+  timeout?: number | undefined
+  callbacks: Partial<TransitionCallbacks>
+  children: VNode[]
+}
+
+type KeyedChild = { key: string | number; element: VNode }
+
+const isVNode = (child: unknown): child is VNode =>
+  child != null && typeof child === "object" && "type" in (child as object)
+
+const getKeyedChildren = (children: VNode[]): KeyedChild[] => {
+  const result: KeyedChild[] = []
+  for (const child of children) {
+    if (isVNode(child)) {
+      const key = (child as VNode & { key?: string | number }).key
+      if (key != null) {
+        result.push({ key, element: child })
+      }
+    }
+  }
+  return result
+}
+
+/**
+ * Renders children with key-based enter/exit animation (no `show` prop).
+ * Children that appear (new key) animate in. Children that disappear
+ * (removed key) stay in DOM during leave animation, then unmount.
+ * config.tag wraps all children as a container element.
+ */
+const GroupRenderer = ({
+  config,
+  htmlProps,
+  appear,
+  timeout,
+  callbacks,
+  children,
+}: GroupRendererProps): VNode | null => {
+  const effectiveAppear = appear ?? config.appear ?? false
+  const effectiveTimeout = timeout ?? config.timeout ?? 5000
+
+  const prevMap = new Map<string | number, VNode>()
+  const leavingMap = new Map<string | number, VNode>()
+  const forceUpdateSignal = signal(0)
+
+  const currentKeyed = getKeyedChildren(children)
+  const currentMap = new Map<string | number, VNode>()
+  for (const { key, element } of currentKeyed) {
+    currentMap.set(key, element)
+  }
+
+  const initialKeys: Set<string | number> = new Set(currentMap.keys())
+
+  // Detect leaving children
+  for (const [key, child] of prevMap) {
+    if (!currentMap.has(key)) {
+      leavingMap.set(key, child)
+    }
+  }
+
+  // If a leaving child reappears, stop leaving
+  for (const key of currentMap.keys()) {
+    leavingMap.delete(key)
+  }
+
+  prevMap.clear()
+  for (const [key, element] of currentMap) {
+    prevMap.set(key, element)
+  }
+
+  const handleAfterLeave = (key: string | number) => {
+    leavingMap.delete(key)
+    callbacks.onAfterLeave?.()
+    forceUpdateSignal.update((c) => c + 1)
+  }
+
+  // Merge current + leaving
+  const allEntries: KeyedChild[] = [...currentKeyed]
+  for (const [key, element] of leavingMap) {
+    allEntries.push({ key, element })
+  }
+
+  const groupedChildren = allEntries.map(({ key, element }) => {
+    const isInitial = initialKeys.has(key)
+    const isShowing = currentMap.has(key)
+
+    return (
+      <TransitionItem
+        show={() => isShowing}
+        appear={isInitial ? effectiveAppear : true}
+        timeout={effectiveTimeout}
+        enterStyle={config.enterStyle}
+        enterToStyle={config.enterToStyle}
+        enterTransition={config.enterTransition}
+        leaveStyle={config.leaveStyle}
+        leaveToStyle={config.leaveToStyle}
+        leaveTransition={config.leaveTransition}
+        enter={config.enter}
+        enterFrom={config.enterFrom}
+        enterTo={config.enterTo}
+        leave={config.leave}
+        leaveFrom={config.leaveFrom}
+        leaveTo={config.leaveTo}
+        onAfterLeave={() => handleAfterLeave(key)}
+      >
+        {element}
+      </TransitionItem>
+    )
+  })
+
+  return h(config.tag, { ...htmlProps }, ...groupedChildren)
+}
+
+export default GroupRenderer

package/src/kinetic/StaggerRenderer.tsx

@@ -0,0 +1,88 @@
+import type { VNode } from "@pyreon/core"
+import { h } from "@pyreon/core"
+import type { CSSProperties, TransitionCallbacks } from "../types"
+import { cloneVNode } from "../utils"
+import TransitionItem from "./TransitionItem"
+import type { KineticConfig } from "./types"
+
+type StaggerRendererProps = {
+  config: KineticConfig
+  htmlProps: Record<string, unknown>
+  show: () => boolean
+  appear?: boolean | undefined
+  timeout?: number | undefined
+  interval?: number | undefined
+  reverseLeave?: boolean | undefined
+  callbacks: Partial<TransitionCallbacks>
+  children: VNode[]
+}
+
+const isVNode = (child: unknown): child is VNode =>
+  child != null && typeof child === "object" && "type" in (child as object)
+
+/**
+ * Renders children with staggered enter/exit animation.
+ * config.tag wraps the staggered children as a container element.
+ * Each child is individually animated via TransitionItem.
+ */
+const StaggerRenderer = ({
+  config,
+  htmlProps,
+  show,
+  appear,
+  timeout,
+  interval,
+  reverseLeave,
+  callbacks,
+  children,
+}: StaggerRendererProps): VNode | null => {
+  const effectiveAppear = appear ?? config.appear ?? false
+  const effectiveTimeout = timeout ?? config.timeout ?? 5000
+  const effectiveInterval = interval ?? config.interval ?? 50
+  const effectiveReverseLeave = reverseLeave ?? config.reverseLeave ?? false
+
+  const childArray = (Array.isArray(children) ? children : [children]).filter(isVNode)
+  const count = childArray.length
+
+  const staggeredChildren = childArray.map((child, index) => {
+    const staggerIndex = !show() && effectiveReverseLeave ? count - 1 - index : index
+    const delay = staggerIndex * effectiveInterval
+
+    return (
+      <TransitionItem
+        key={(child as VNode & { key?: string | number }).key ?? index}
+        show={show}
+        appear={effectiveAppear}
+        timeout={effectiveTimeout + delay}
+        enterStyle={config.enterStyle}
+        enterToStyle={config.enterToStyle}
+        enterTransition={config.enterTransition}
+        leaveStyle={config.leaveStyle}
+        leaveToStyle={config.leaveToStyle}
+        leaveTransition={config.leaveTransition}
+        enter={config.enter}
+        enterFrom={config.enterFrom}
+        enterTo={config.enterTo}
+        leave={config.leave}
+        leaveFrom={config.leaveFrom}
+        leaveTo={config.leaveTo}
+        onAfterLeave={
+          index === (effectiveReverseLeave ? 0 : count - 1) ? callbacks.onAfterLeave : undefined
+        }
+      >
+        {cloneVNode(child, {
+          style: {
+            ...((child.props as Record<string, unknown>)?.style as CSSProperties | undefined),
+            "--stagger-index": staggerIndex,
+            "--stagger-interval": `${effectiveInterval}ms`,
+            transitionDelay: `${delay}ms`,
+          } as CSSProperties,
+        })}
+      </TransitionItem>
+    )
+  })
+
+  return h(config.tag, { ...htmlProps }, ...staggeredChildren)
+}
+
+export default StaggerRenderer

package/src/kinetic/TransitionItem.tsx

@@ -0,0 +1,196 @@
+import type { VNode } from "@pyreon/core"
+import { createRef, 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"
+
+type TransitionItemProps = ClassTransitionProps &
+  StyleTransitionProps &
+  TransitionCallbacks & {
+    show: () => boolean
+    appear?: boolean | undefined
+    unmount?: boolean | undefined
+    timeout?: number | undefined
+    delay?: number | undefined
+    children: VNode
+  }
+
+const applyEnter = (el: HTMLElement, config: ClassTransitionProps & StyleTransitionProps) => {
+  addClasses(el, config.enter)
+  addClasses(el, config.enterFrom)
+  if (config.enterStyle) Object.assign(el.style, config.enterStyle)
+  if (config.enterTransition) el.style.transition = config.enterTransition
+
+  return nextFrame(() => {
+    removeClasses(el, config.enterFrom)
+    addClasses(el, config.enterTo)
+    if (config.enterToStyle) Object.assign(el.style, config.enterToStyle)
+  })
+}
+
+const applyLeave = (el: HTMLElement, config: ClassTransitionProps & StyleTransitionProps) => {
+  removeClasses(el, config.enter)
+  removeClasses(el, config.enterTo)
+
+  addClasses(el, config.leave)
+  addClasses(el, config.leaveFrom)
+  if (config.leaveStyle) Object.assign(el.style, config.leaveStyle)
+  if (config.leaveTransition) el.style.transition = config.leaveTransition
+
+  return nextFrame(() => {
+    removeClasses(el, config.leaveFrom)
+    addClasses(el, config.leaveTo)
+    if (config.leaveToStyle) Object.assign(el.style, config.leaveToStyle)
+  })
+}
+
+const applyReducedMotion = (
+  stage: string,
+  callbacks: Partial<TransitionCallbacks>,
+  complete: () => void,
+) => {
+  if (stage === "entering") {
+    callbacks.onEnter?.()
+    callbacks.onAfterEnter?.()
+    complete()
+  } else if (stage === "leaving") {
+    callbacks.onLeave?.()
+    callbacks.onAfterLeave?.()
+    complete()
+  }
+}
+
+/**
+ * Internal per-child transition component. Used by StaggerRenderer and
+ * GroupRenderer to give each child its own animation state.
+ *
+ * Uses cloneVNode to inject ref onto the child — the child must accept ref.
+ */
+const TransitionItem = ({
+  show,
+  appear = false,
+  unmount = true,
+  timeout = 5000,
+  enter,
+  enterFrom,
+  enterTo,
+  leave,
+  leaveFrom,
+  leaveTo,
+  enterStyle,
+  enterToStyle,
+  enterTransition,
+  leaveStyle,
+  leaveToStyle,
+  leaveTransition,
+  onEnter,
+  onAfterEnter,
+  onLeave,
+  onAfterLeave,
+  children,
+}: TransitionItemProps): VNode | null => {
+  const reducedMotion = useReducedMotion()
+  const { stage, ref: stateRef, shouldMount, complete } = useTransitionState({ show, appear })
+
+  const elementRef = createRef<HTMLElement>()
+  const mergedRef = mergeRefs(
+    elementRef,
+    stateRef,
+    (children.props as Record<string, unknown>)?.ref as
+      | ((el: HTMLElement | null) => void)
+      | undefined,
+  )
+
+  const callbacks = {
+    onEnter,
+    onAfterEnter,
+    onLeave,
+    onAfterLeave,
+  }
+
+  const transitionConfig = {
+    enter,
+    enterFrom,
+    enterTo,
+    leave,
+    leaveFrom,
+    leaveTo,
+    enterStyle,
+    enterToStyle,
+    enterTransition,
+    leaveStyle,
+    leaveToStyle,
+    leaveTransition,
+  }
+
+  useAnimationEnd({
+    ref: elementRef,
+    active: () => (stage() === "entering" || stage() === "leaving") && !reducedMotion(),
+    timeout,
+    onEnd: () => {
+      if (stage() === "entering") {
+        callbacks.onAfterEnter?.()
+      } else if (stage() === "leaving") {
+        callbacks.onAfterLeave?.()
+      }
+      complete()
+    },
+  })
+
+  watch(
+    () => stage(),
+    (currentStage) => {
+      const el = elementRef.current
+      if (!el) return
+
+      if (reducedMotion()) {
+        applyReducedMotion(currentStage, callbacks, complete)
+        return
+      }
+
+      if (currentStage === "entering") {
+        callbacks.onEnter?.()
+        const frameId = applyEnter(el, transitionConfig)
+        return () => cancelAnimationFrame(frameId)
+      }
+
+      if (currentStage === "leaving") {
+        callbacks.onLeave?.()
+        const frameId = applyLeave(el, transitionConfig)
+        return () => cancelAnimationFrame(frameId)
+      }
+
+      if (currentStage === "entered") {
+        removeClasses(el, enter)
+        el.style.transition = ""
+      }
+    },
+    { immediate: true },
+  )
+
+  return (
+    <Show
+      when={shouldMount}
+      fallback={
+        unmount
+          ? null
+          : cloneVNode(children, {
+              ref: mergedRef,
+              style: mergeStyles(
+                (children.props as Record<string, unknown>)?.style as
+                  | Record<string, string | number | undefined>
+                  | undefined,
+                { display: "none" },
+              ),
+            })
+      }
+    >
+      {cloneVNode(children, { ref: mergedRef })}
+    </Show>
+  )
+}
+
+export default TransitionItem