@pyreon/kinetic 0.11.1 → 0.11.2

package/src/types.ts

@@ -0,0 +1,118 @@
+import type { Ref, VNode } from "@pyreon/core"
+import type { Signal } from "@pyreon/reactivity"
+
+export type CSSProperties = Record<string, string | number | undefined>
+
+/** Internal lifecycle stages of a transition. */
+export type TransitionStage = "hidden" | "entering" | "entered" | "leaving"
+
+/** Class-based transition definition. */
+export type ClassTransitionProps = {
+  /** Classes applied during the entire enter phase */
+  enter?: string | undefined
+  /** Classes applied on first frame of enter, removed on next frame */
+  enterFrom?: string | undefined
+  /** Classes applied on second frame of enter, kept until complete */
+  enterTo?: string | undefined
+  /** Classes applied during the entire leave phase */
+  leave?: string | undefined
+  /** Classes applied on first frame of leave */
+  leaveFrom?: string | undefined
+  /** Classes applied on second frame of leave, kept until complete */
+  leaveTo?: string | undefined
+}
+
+/** Style-object transition definition (zero-CSS option). */
+export type StyleTransitionProps = {
+  /** Inline styles for the start of enter */
+  enterStyle?: CSSProperties | undefined
+  /** Inline styles for the end of enter */
+  enterToStyle?: CSSProperties | undefined
+  /** CSS transition shorthand applied during enter */
+  enterTransition?: string | undefined
+  /** Inline styles for the start of leave */
+  leaveStyle?: CSSProperties | undefined
+  /** Inline styles for the end of leave */
+  leaveToStyle?: CSSProperties | undefined
+  /** CSS transition shorthand applied during leave */
+  leaveTransition?: string | undefined
+}
+
+/** Lifecycle callbacks. */
+export type TransitionCallbacks = {
+  /** Called immediately when entering begins */
+  onEnter?: (() => void) | undefined
+  /** Called when enter animation completes */
+  onAfterEnter?: (() => void) | undefined
+  /** Called immediately when leaving begins */
+  onLeave?: (() => void) | undefined
+  /** Called when leave animation completes */
+  onAfterLeave?: (() => void) | undefined
+}
+
+export type TransitionProps = ClassTransitionProps &
+  StyleTransitionProps &
+  TransitionCallbacks & {
+    /** Reactive accessor controlling visibility. true = enter, false = leave + unmount. */
+    show: () => boolean
+    /** If true, runs enter animation on initial mount. Default: false. */
+    appear?: boolean | undefined
+    /** If true (default), unmounts when hidden. If false, keeps with display:none. */
+    unmount?: boolean | undefined
+    /** Safety timeout in ms. Default: 5000. */
+    timeout?: number | undefined
+    /** Single child element. Must accept ref. */
+    children: VNode
+  }
+
+export type TransitionGroupProps = ClassTransitionProps &
+  StyleTransitionProps &
+  TransitionCallbacks & {
+    /** If true, animates initial children on mount. Default: false. */
+    appear?: boolean | undefined
+    /** Safety timeout in ms. Default: 5000. */
+    timeout?: number | undefined
+    /** Children with unique keys. */
+    children: VNode[]
+  }
+
+export type StaggerProps = ClassTransitionProps &
+  StyleTransitionProps &
+  TransitionCallbacks & {
+    /** Reactive accessor controlling visibility of all children. */
+    show: () => boolean
+    /** Delay between each child's animation start in ms. Default: 50. */
+    interval?: number | undefined
+    /** If true, reverses stagger order on leave. Default: false. */
+    reverseLeave?: boolean | undefined
+    /** If true, animates on initial mount. Default: false. */
+    appear?: boolean | undefined
+    /** Safety timeout in ms. Default: 5000. */
+    timeout?: number | undefined
+    /** Children to stagger. */
+    children: VNode[]
+  }
+
+export type CollapseProps = TransitionCallbacks & {
+  /** Reactive accessor controlling expanded/collapsed state. */
+  show: () => boolean
+  /** CSS transition for height. Default: "height 300ms ease". */
+  transition?: string | undefined
+  /** If true, animates on initial mount. Default: false. */
+  appear?: boolean | undefined
+  /** Safety timeout in ms. Default: 5000. */
+  timeout?: number | undefined
+  /** The content to collapse. */
+  children: VNode
+}
+
+export type TransitionStateResult = {
+  /** Current lifecycle stage (signal) */
+  stage: Signal<TransitionStage>
+  /** Ref callback to attach to the transitioning element */
+  ref: Ref<HTMLElement> | ((node: HTMLElement | null) => void)
+  /** Reactive accessor: whether the element should be rendered */
+  shouldMount: () => boolean
+  /** Call when the current animation finishes */
+  complete: () => void
+}

package/src/useAnimationEnd.ts

@@ -0,0 +1,59 @@
+import type { Ref } from "@pyreon/core"
+import { watch } from "@pyreon/reactivity"
+
+const DEFAULT_TIMEOUT = 5000
+
+export type UseAnimationEnd = (options: {
+  ref: Ref<HTMLElement>
+  onEnd: () => void
+  active: () => boolean
+  timeout?: number | undefined
+}) => void
+
+const useAnimationEnd: UseAnimationEnd = ({ ref, onEnd, active, timeout = DEFAULT_TIMEOUT }) => {
+  let called = false
+
+  watch(
+    active,
+    (isActive) => {
+      if (!isActive) {
+        called = false
+        return
+      }
+
+      const el = ref.current
+      if (!el) return
+
+      called = false
+
+      const done = () => {
+        if (called) return
+        called = true
+        el.removeEventListener("transitionend", handleEnd)
+        el.removeEventListener("animationend", handleEnd)
+        clearTimeout(timer)
+        onEnd()
+      }
+
+      const handleEnd = (e: Event) => {
+        // Ignore bubbled events from children
+        if (e.target !== el) return
+        done()
+      }
+
+      el.addEventListener("transitionend", handleEnd)
+      el.addEventListener("animationend", handleEnd)
+
+      const timer = setTimeout(done, timeout)
+
+      return () => {
+        el.removeEventListener("transitionend", handleEnd)
+        el.removeEventListener("animationend", handleEnd)
+        clearTimeout(timer)
+      }
+    },
+    { immediate: true },
+  )
+}
+
+export default useAnimationEnd

package/src/useReducedMotion.ts

@@ -0,0 +1,28 @@
+import { onMount, onUnmount } from "@pyreon/core"
+import { signal } from "@pyreon/reactivity"
+
+/**
+ * Inline reduced-motion check for kinetic package.
+ * Avoids depending on @pyreon/hooks for a single media query.
+ */
+export function useReducedMotion(): () => boolean {
+  const matches = signal(false)
+  let mql: MediaQueryList | undefined
+
+  const onChange = (e: MediaQueryListEvent) => {
+    matches.set(e.matches)
+  }
+
+  onMount(() => {
+    mql = window.matchMedia("(prefers-reduced-motion: reduce)")
+    matches.set(mql.matches)
+    mql.addEventListener("change", onChange)
+    return undefined
+  })
+
+  onUnmount(() => {
+    mql?.removeEventListener("change", onChange)
+  })
+
+  return matches
+}

package/src/useTransitionState.ts

@@ -0,0 +1,62 @@
+import { createRef } from "@pyreon/core"
+import { runUntracked, signal, watch } from "@pyreon/reactivity"
+import type { TransitionStage, TransitionStateResult } from "./types"
+
+export type UseTransitionState = (options: {
+  show: () => boolean
+  appear?: boolean | undefined
+}) => TransitionStateResult
+
+const useTransitionState: UseTransitionState = ({ show, appear = false }) => {
+  const initialShow = show()
+  // When appear=true and show starts true, mount the element (stage='entered')
+  // but defer the enter animation until the ref is connected.
+  const needsAppear = appear && initialShow
+  const stage = signal<TransitionStage>(initialShow ? "entered" : "hidden")
+  const elementRef = createRef<HTMLElement>()
+  let isInitialMount = true
+  let appearTriggered = false
+
+  // Ref callback that triggers the appear animation once the element is wired
+  const refCallback = (node: HTMLElement | null) => {
+    elementRef.current = node
+    if (node && needsAppear && !appearTriggered) {
+      appearTriggered = true
+      stage.set("entering")
+    }
+  }
+
+  watch(
+    show,
+    (showVal) => {
+      if (isInitialMount) {
+        isInitialMount = false
+        // appear case is handled by refCallback 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 },
+  )
+
+  const complete = () => {
+    const current = stage()
+    if (current === "entering") stage.set("entered")
+    if (current === "leaving") stage.set("hidden")
+  }
+
+  return {
+    stage,
+    ref: refCallback,
+    shouldMount: () => stage() !== "hidden",
+    complete,
+  }
+}
+
+export default useTransitionState

package/src/utils.ts

@@ -0,0 +1,81 @@
+import type { Ref, VNode } from "@pyreon/core"
+import type { CSSProperties } from "./types"
+
+const splitCache = new Map<string, string[]>()
+const splitClasses = (classes: string): string[] => {
+  let cached = splitCache.get(classes)
+  if (!cached) {
+    cached = classes.split(/\s+/).filter(Boolean)
+    splitCache.set(classes, cached)
+  }
+  return cached
+}
+
+/** Adds space-separated CSS classes to an element. */
+export const addClasses = (el: HTMLElement, classes: string | undefined) => {
+  if (!classes) return
+  const list = splitClasses(classes)
+  if (list.length > 0) el.classList.add(...list)
+}
+
+/** Removes space-separated CSS classes from an element. */
+export const removeClasses = (el: HTMLElement, classes: string | undefined) => {
+  if (!classes) return
+  const list = splitClasses(classes)
+  if (list.length > 0) el.classList.remove(...list)
+}
+
+/**
+ * Executes callback after two animation frames (double-rAF).
+ * Ensures the browser paints the current state before applying changes,
+ * which is required for CSS transitions to trigger.
+ */
+export const nextFrame = (callback: () => void): number =>
+  requestAnimationFrame(() => {
+    requestAnimationFrame(callback)
+  })
+
+/** Merges two className strings, filtering undefined/empty. */
+export const mergeClassNames = (
+  existing: string | undefined,
+  additional: string | undefined,
+): string | undefined => {
+  const parts = [existing, additional].filter(Boolean)
+  return parts.length > 0 ? parts.join(" ") : undefined
+}
+
+/** Merges two CSSProperties objects, with `b` taking precedence. */
+export const mergeStyles = (
+  a: CSSProperties | undefined,
+  b: CSSProperties | undefined,
+): CSSProperties | undefined => {
+  if (!a && !b) return undefined
+  if (!a) return b
+  if (!b) return a
+  return { ...a, ...b }
+}
+
+// ─── Ref & Motion Utilities ─────────────────────────────────
+
+type RefCallback<T> = (node: T | null) => void
+type RefLike<T> = RefCallback<T> | Ref<T>
+
+/** Merges multiple refs (callback or object) into a single callback ref. */
+export const mergeRefs = <T>(...refs: (RefLike<T> | undefined)[]): ((node: T | null) => void) => {
+  return (node: T | null) => {
+    for (const ref of refs) {
+      if (!ref) continue
+      if (typeof ref === "function") {
+        ref(node)
+      } else {
+        ;(ref as { current: unknown }).current = node
+      }
+    }
+  }
+}
+
+/** Clones a VNode with merged props. */
+export const cloneVNode = (vnode: VNode, extraProps: Record<string, unknown>): VNode => ({
+  ...vnode,
+  props: { ...vnode.props, ...extraProps },
+})