@pyreon/kinetic 0.11.0 → 0.11.2

package/src/__tests__/useAnimationEnd.test.ts

@@ -0,0 +1,194 @@
+import { signal } from "@pyreon/reactivity"
+import useAnimationEnd from "../useAnimationEnd"
+
+const createMockRef = () => {
+  const el = document.createElement("div")
+  return { current: el }
+}
+
+describe("useAnimationEnd", () => {
+  beforeEach(() => vi.useFakeTimers())
+  afterEach(() => vi.useRealTimers())
+
+  it("calls onEnd when transitionend fires on the element", () => {
+    const onEnd = vi.fn()
+    const ref = createMockRef()
+    const active = signal(true)
+
+    useAnimationEnd({ ref, onEnd, active })
+
+    const event = new Event("transitionend", { bubbles: true })
+    Object.defineProperty(event, "target", { value: ref.current })
+    ref.current.dispatchEvent(event)
+
+    expect(onEnd).toHaveBeenCalledTimes(1)
+  })
+
+  it("calls onEnd when animationend fires on the element", () => {
+    const onEnd = vi.fn()
+    const ref = createMockRef()
+    const active = signal(true)
+
+    useAnimationEnd({ ref, onEnd, active })
+
+    const event = new Event("animationend", { bubbles: true })
+    Object.defineProperty(event, "target", { value: ref.current })
+    ref.current.dispatchEvent(event)
+
+    expect(onEnd).toHaveBeenCalledTimes(1)
+  })
+
+  it("ignores bubbled events from children", () => {
+    const onEnd = vi.fn()
+    const ref = createMockRef()
+    const child = document.createElement("span")
+    ref.current.appendChild(child)
+    const active = signal(true)
+
+    useAnimationEnd({ ref, onEnd, active })
+
+    const event = new Event("transitionend", { bubbles: true })
+    child.dispatchEvent(event)
+
+    expect(onEnd).not.toHaveBeenCalled()
+  })
+
+  it("fires timeout fallback when no event fires", () => {
+    const onEnd = vi.fn()
+    const ref = createMockRef()
+    const active = signal(true)
+
+    useAnimationEnd({ ref, onEnd, active, timeout: 1000 })
+
+    expect(onEnd).not.toHaveBeenCalled()
+
+    vi.advanceTimersByTime(1000)
+
+    expect(onEnd).toHaveBeenCalledTimes(1)
+  })
+
+  it("uses default timeout of 5000ms", () => {
+    const onEnd = vi.fn()
+    const ref = createMockRef()
+    const active = signal(true)
+
+    useAnimationEnd({ ref, onEnd, active })
+
+    vi.advanceTimersByTime(4999)
+    expect(onEnd).not.toHaveBeenCalled()
+
+    vi.advanceTimersByTime(1)
+    expect(onEnd).toHaveBeenCalledTimes(1)
+  })
+
+  it("only fires onEnd once even if multiple events fire", () => {
+    const onEnd = vi.fn()
+    const ref = createMockRef()
+    const active = signal(true)
+
+    useAnimationEnd({ ref, onEnd, active })
+
+    const event1 = new Event("transitionend", { bubbles: true })
+    Object.defineProperty(event1, "target", { value: ref.current })
+    ref.current.dispatchEvent(event1)
+
+    const event2 = new Event("animationend", { bubbles: true })
+    Object.defineProperty(event2, "target", { value: ref.current })
+    ref.current.dispatchEvent(event2)
+
+    expect(onEnd).toHaveBeenCalledTimes(1)
+  })
+
+  it("does not fire when active is false", () => {
+    const onEnd = vi.fn()
+    const ref = createMockRef()
+    const active = signal(false)
+
+    useAnimationEnd({ ref, onEnd, active, timeout: 100 })
+
+    vi.advanceTimersByTime(200)
+
+    expect(onEnd).not.toHaveBeenCalled()
+  })
+
+  it("does not fire when active=true but ref.current is null", () => {
+    const onEnd = vi.fn()
+    const ref = { current: null } as { current: HTMLElement | null }
+    const active = signal(true)
+
+    useAnimationEnd({ ref, onEnd, active, timeout: 100 })
+
+    // No timer should be set when ref is null
+    vi.advanceTimersByTime(200)
+
+    expect(onEnd).not.toHaveBeenCalled()
+  })
+
+  it("does not call onEnd twice when transitionend fires and then timeout fires", () => {
+    const onEnd = vi.fn()
+    const ref = createMockRef()
+    const active = signal(true)
+
+    useAnimationEnd({ ref, onEnd, active, timeout: 1000 })
+
+    // First: transitionend fires — calls done()
+    const event = new Event("transitionend", { bubbles: true })
+    Object.defineProperty(event, "target", { value: ref.current })
+    ref.current.dispatchEvent(event)
+
+    expect(onEnd).toHaveBeenCalledTimes(1)
+
+    // Second: timeout fires — should be no-op because called is true
+    vi.advanceTimersByTime(1000)
+
+    expect(onEnd).toHaveBeenCalledTimes(1)
+  })
+
+  it("does not call onEnd twice when timeout fires and then transitionend fires", () => {
+    const onEnd = vi.fn()
+    const ref = createMockRef()
+    const active = signal(true)
+
+    useAnimationEnd({ ref, onEnd, active, timeout: 500 })
+
+    // First: timeout fires — calls done()
+    vi.advanceTimersByTime(500)
+
+    expect(onEnd).toHaveBeenCalledTimes(1)
+
+    // Second: transitionend fires — should be no-op via called guard
+    const event = new Event("transitionend", { bubbles: true })
+    Object.defineProperty(event, "target", { value: ref.current })
+    ref.current.dispatchEvent(event)
+
+    expect(onEnd).toHaveBeenCalledTimes(1)
+  })
+
+  it("resets called when active transitions from true to false", () => {
+    const onEnd = vi.fn()
+    const ref = createMockRef()
+    const active = signal(true)
+
+    useAnimationEnd({ ref, onEnd, active, timeout: 1000 })
+
+    // Fire to set called = true
+    const event = new Event("transitionend", { bubbles: true })
+    Object.defineProperty(event, "target", { value: ref.current })
+    ref.current.dispatchEvent(event)
+
+    expect(onEnd).toHaveBeenCalledTimes(1)
+
+    // Deactivate — resets called
+    active.set(false)
+
+    // Re-activate
+    active.set(true)
+
+    // Should be able to fire again
+    const event2 = new Event("transitionend", { bubbles: true })
+    Object.defineProperty(event2, "target", { value: ref.current })
+    ref.current.dispatchEvent(event2)
+
+    expect(onEnd).toHaveBeenCalledTimes(2)
+  })
+})

package/src/__tests__/useReducedMotion.test.ts

@@ -0,0 +1,157 @@
+// Track lifecycle callbacks
+let mountCallbacks: Array<() => undefined | (() => void)> = []
+let unmountCallbacks: Array<() => void> = []
+
+vi.mock("@pyreon/core", () => ({
+  onMount: vi.fn((cb: () => undefined | (() => void)) => {
+    mountCallbacks.push(cb)
+  }),
+  onUnmount: vi.fn((cb: () => void) => {
+    unmountCallbacks.push(cb)
+  }),
+}))
+
+vi.mock("@pyreon/reactivity", () => {
+  const signal = <T>(initial: T) => {
+    let value = initial
+    const s = (() => value) as (() => T) & {
+      set: (v: T) => void
+      update: (fn: (c: T) => T) => void
+      peek: () => T
+      subscribe: () => () => void
+      direct: () => () => void
+      label: string | undefined
+      debug: () => { name: string | undefined; value: T; subscriberCount: number }
+    }
+    s.set = (v: T) => {
+      value = v
+    }
+    s.update = (fn: (c: T) => T) => {
+      value = fn(value)
+    }
+    s.peek = () => value
+    s.subscribe = () => () => undefined
+    s.direct = () => () => undefined
+    s.label = undefined
+    s.debug = () => ({ name: undefined, value, subscriberCount: 0 })
+    return s
+  }
+  return { signal }
+})
+
+import { useReducedMotion } from "../useReducedMotion"
+
+describe("useReducedMotion", () => {
+  let changeHandlers: Array<(e: any) => void>
+  let removedHandlers: Array<(e: any) => void>
+
+  const createMockMQL = (matches: boolean) => ({
+    matches,
+    media: "(prefers-reduced-motion: reduce)",
+    addEventListener: vi.fn((event: string, handler: (e: any) => void) => {
+      if (event === "change") changeHandlers.push(handler)
+    }),
+    removeEventListener: vi.fn((event: string, handler: (e: any) => void) => {
+      if (event === "change") removedHandlers.push(handler)
+    }),
+  })
+
+  beforeEach(() => {
+    mountCallbacks = []
+    unmountCallbacks = []
+    changeHandlers = []
+    removedHandlers = []
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it("returns false initially", () => {
+    vi.stubGlobal(
+      "matchMedia",
+      vi.fn(() => createMockMQL(false)),
+    )
+    const result = useReducedMotion()
+    expect(result()).toBe(false)
+  })
+
+  it("reads matchMedia state on mount (true)", () => {
+    vi.stubGlobal(
+      "matchMedia",
+      vi.fn(() => createMockMQL(true)),
+    )
+    const result = useReducedMotion()
+
+    // Fire mount callback
+    for (const cb of mountCallbacks) cb()
+
+    expect(result()).toBe(true)
+  })
+
+  it("reads matchMedia state on mount (false)", () => {
+    vi.stubGlobal(
+      "matchMedia",
+      vi.fn(() => createMockMQL(false)),
+    )
+    const result = useReducedMotion()
+
+    for (const cb of mountCallbacks) cb()
+
+    expect(result()).toBe(false)
+  })
+
+  it("reacts to change events", () => {
+    vi.stubGlobal(
+      "matchMedia",
+      vi.fn(() => createMockMQL(false)),
+    )
+    const result = useReducedMotion()
+
+    for (const cb of mountCallbacks) cb()
+    expect(result()).toBe(false)
+
+    // Simulate preference change
+    for (const handler of changeHandlers) {
+      handler({ matches: true })
+    }
+
+    expect(result()).toBe(true)
+  })
+
+  it("queries the correct media string", () => {
+    const mockMatchMedia = vi.fn(() => createMockMQL(false))
+    vi.stubGlobal("matchMedia", mockMatchMedia)
+
+    useReducedMotion()
+    for (const cb of mountCallbacks) cb()
+
+    expect(mockMatchMedia).toHaveBeenCalledWith("(prefers-reduced-motion: reduce)")
+  })
+
+  it("registers a change listener on mount", () => {
+    vi.stubGlobal(
+      "matchMedia",
+      vi.fn(() => createMockMQL(false)),
+    )
+    useReducedMotion()
+
+    for (const cb of mountCallbacks) cb()
+
+    expect(changeHandlers).toHaveLength(1)
+  })
+
+  it("removes the change listener on unmount", () => {
+    vi.stubGlobal(
+      "matchMedia",
+      vi.fn(() => createMockMQL(false)),
+    )
+    useReducedMotion()
+
+    for (const cb of mountCallbacks) cb()
+    expect(changeHandlers).toHaveLength(1)
+
+    for (const cb of unmountCallbacks) cb()
+    expect(removedHandlers).toHaveLength(1)
+  })
+})

package/src/__tests__/useTransitionState.test.ts

@@ -0,0 +1,132 @@
+import { signal } from "@pyreon/reactivity"
+import useTransitionState from "../useTransitionState"
+
+describe("useTransitionState", () => {
+  it("initial state is hidden when show=false", () => {
+    const show = signal(false)
+    const result = useTransitionState({ show })
+    expect(result.stage()).toBe("hidden")
+    expect(result.shouldMount()).toBe(false)
+  })
+
+  it("initial state is entered when show=true and appear=false", () => {
+    const show = signal(true)
+    const result = useTransitionState({ show })
+    expect(result.stage()).toBe("entered")
+    expect(result.shouldMount()).toBe(true)
+  })
+
+  it("transitions to entering when show changes false->true", () => {
+    const show = signal(false)
+    const result = useTransitionState({ show })
+
+    expect(result.stage()).toBe("hidden")
+
+    show.set(true)
+    expect(result.stage()).toBe("entering")
+    expect(result.shouldMount()).toBe(true)
+  })
+
+  it("complete() transitions entering->entered", () => {
+    const show = signal(false)
+    const result = useTransitionState({ show })
+
+    show.set(true)
+    expect(result.stage()).toBe("entering")
+
+    result.complete()
+    expect(result.stage()).toBe("entered")
+  })
+
+  it("transitions to leaving when show changes true->false", () => {
+    const show = signal(true)
+    const result = useTransitionState({ show })
+
+    expect(result.stage()).toBe("entered")
+
+    show.set(false)
+    expect(result.stage()).toBe("leaving")
+    expect(result.shouldMount()).toBe(true)
+  })
+
+  it("complete() transitions leaving->hidden", () => {
+    const show = signal(true)
+    const result = useTransitionState({ show })
+
+    show.set(false)
+    expect(result.stage()).toBe("leaving")
+
+    result.complete()
+    expect(result.stage()).toBe("hidden")
+    expect(result.shouldMount()).toBe(false)
+  })
+
+  it("appear=true enters after ref is connected", () => {
+    const show = signal(true)
+    const result = useTransitionState({ show, appear: true })
+    // Before ref is wired, element should be mounted but stage is 'entered'
+    expect(result.stage()).toBe("entered")
+    expect(result.shouldMount()).toBe(true)
+
+    // Simulate ref connection (as the renderer would do)
+    const el = document.createElement("div")
+    if (typeof result.ref === "function") {
+      result.ref(el)
+    }
+    // Now the appear animation should trigger
+    expect(result.stage()).toBe("entering")
+  })
+
+  it("complete() is a no-op in entered state", () => {
+    const show = signal(true)
+    const result = useTransitionState({ show })
+
+    expect(result.stage()).toBe("entered")
+
+    result.complete()
+    expect(result.stage()).toBe("entered")
+  })
+
+  it("complete() is a no-op in hidden state", () => {
+    const show = signal(false)
+    const result = useTransitionState({ show })
+
+    expect(result.stage()).toBe("hidden")
+
+    result.complete()
+    expect(result.stage()).toBe("hidden")
+  })
+
+  it("handles rapid toggling true->false->true", () => {
+    const show = signal(true)
+    const result = useTransitionState({ show })
+
+    // Start leave
+    show.set(false)
+    expect(result.stage()).toBe("leaving")
+
+    // Interrupt with enter before leave completes
+    show.set(true)
+    expect(result.stage()).toBe("entering")
+  })
+
+  it("handles rapid toggling false->true->false (entering to leaving)", () => {
+    const show = signal(false)
+    const result = useTransitionState({ show })
+
+    // Start enter
+    show.set(true)
+    expect(result.stage()).toBe("entering")
+
+    // Interrupt with leave before enter completes
+    show.set(false)
+    expect(result.stage()).toBe("leaving")
+  })
+
+  it("provides a ref (callback or object)", () => {
+    const show = signal(false)
+    const result = useTransitionState({ show })
+    expect(result.ref).toBeDefined()
+    expect(typeof result.ref === "function" || "current" in result.ref).toBe(true)
+  })
+})

package/src/__tests__/utils.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, it } from "vitest"
+import type { CSSProperties } from "../types"
+import { addClasses, mergeClassNames, mergeStyles, nextFrame, removeClasses } from "../utils"
+
+describe("mergeClassNames", () => {
+  it("merges two class strings", () => {
+    expect(mergeClassNames("a", "b")).toBe("a b")
+  })
+
+  it("returns existing when additional is undefined", () => {
+    expect(mergeClassNames("a", undefined)).toBe("a")
+  })
+
+  it("returns additional when existing is undefined", () => {
+    expect(mergeClassNames(undefined, "b")).toBe("b")
+  })
+
+  it("returns undefined when both are undefined", () => {
+    expect(mergeClassNames(undefined, undefined)).toBeUndefined()
+  })
+
+  it("returns undefined when both are empty strings", () => {
+    expect(mergeClassNames("", "")).toBeUndefined()
+  })
+
+  it("filters out empty strings", () => {
+    expect(mergeClassNames("a", "")).toBe("a")
+  })
+})
+
+describe("mergeStyles", () => {
+  it("merges two style objects with b taking precedence", () => {
+    const a = { color: "red", fontSize: "12px" } as CSSProperties
+    const b = { color: "blue" } as CSSProperties
+    expect(mergeStyles(a, b)).toEqual({ color: "blue", fontSize: "12px" })
+  })
+
+  it("returns undefined when both are undefined", () => {
+    expect(mergeStyles(undefined, undefined)).toBeUndefined()
+  })
+
+  it("returns b when a is undefined", () => {
+    const b = { color: "blue" } as CSSProperties
+    expect(mergeStyles(undefined, b)).toBe(b)
+  })
+
+  it("returns a when b is undefined", () => {
+    const a = { color: "red" } as CSSProperties
+    expect(mergeStyles(a, undefined)).toBe(a)
+  })
+})
+
+describe("addClasses", () => {
+  it("adds space-separated classes to an element", () => {
+    const el = document.createElement("div")
+    addClasses(el, "foo bar")
+    expect(el.classList.contains("foo")).toBe(true)
+    expect(el.classList.contains("bar")).toBe(true)
+  })
+
+  it("does nothing when classes is undefined", () => {
+    const el = document.createElement("div")
+    addClasses(el, undefined)
+    expect(el.classList.length).toBe(0)
+  })
+
+  it("does nothing when classes is empty string", () => {
+    const el = document.createElement("div")
+    addClasses(el, "")
+    expect(el.classList.length).toBe(0)
+  })
+
+  it("does nothing when classes is whitespace-only", () => {
+    const el = document.createElement("div")
+    addClasses(el, "   ")
+    expect(el.classList.length).toBe(0)
+  })
+})
+
+describe("removeClasses", () => {
+  it("removes space-separated classes from an element", () => {
+    const el = document.createElement("div")
+    el.classList.add("foo", "bar", "baz")
+    removeClasses(el, "foo bar")
+    expect(el.classList.contains("foo")).toBe(false)
+    expect(el.classList.contains("bar")).toBe(false)
+    expect(el.classList.contains("baz")).toBe(true)
+  })
+
+  it("does nothing when classes is undefined", () => {
+    const el = document.createElement("div")
+    el.classList.add("foo")
+    removeClasses(el, undefined)
+    expect(el.classList.contains("foo")).toBe(true)
+  })
+
+  it("does nothing when classes is empty string", () => {
+    const el = document.createElement("div")
+    el.classList.add("foo")
+    removeClasses(el, "")
+    expect(el.classList.contains("foo")).toBe(true)
+  })
+
+  it("does nothing when classes is whitespace-only", () => {
+    const el = document.createElement("div")
+    el.classList.add("foo")
+    removeClasses(el, "   ")
+    expect(el.classList.contains("foo")).toBe(true)
+  })
+})
+
+describe("nextFrame", () => {
+  it("calls callback after double rAF", () => {
+    const callbacks: (() => void)[] = []
+    const originalRaf = globalThis.requestAnimationFrame
+    globalThis.requestAnimationFrame = ((cb: () => void) => {
+      callbacks.push(cb)
+      return callbacks.length
+    }) as typeof requestAnimationFrame
+
+    const fn = vi.fn()
+    nextFrame(fn)
+
+    // First rAF queued
+    expect(callbacks.length).toBe(1)
+    expect(fn).not.toHaveBeenCalled()
+
+    // Execute first rAF — queues second
+    callbacks[0]?.()
+    expect(callbacks.length).toBe(2)
+    expect(fn).not.toHaveBeenCalled()
+
+    // Execute second rAF — callback fires
+    callbacks[1]?.()
+    expect(fn).toHaveBeenCalledTimes(1)
+
+    globalThis.requestAnimationFrame = originalRaf
+  })
+})

package/src/index.ts

@@ -0,0 +1,23 @@
+export { default as kinetic } from "./kinetic"
+export type { KineticComponent } from "./kinetic/types"
+export type { Preset } from "./presets"
+export {
+  fade,
+  presets,
+  scaleIn,
+  slideDown,
+  slideLeft,
+  slideRight,
+  slideUp,
+} from "./presets"
+export type {
+  ClassTransitionProps,
+  StyleTransitionProps,
+  TransitionCallbacks,
+  TransitionStage,
+  TransitionStateResult,
+} from "./types"
+export type { UseAnimationEnd } from "./useAnimationEnd"
+export { default as useAnimationEnd } from "./useAnimationEnd"
+export type { UseTransitionState } from "./useTransitionState"
+export { default as useTransitionState } from "./useTransitionState"

package/src/jsx-augment.d.ts

@@ -0,0 +1,12 @@
+// Augment JSX namespace so that `key` is accepted on component elements,
+// not just intrinsic HTML elements. Pyreon's jsx() runtime already handles
+// key as the third argument — this just satisfies TypeScript.
+declare global {
+  namespace JSX {
+    interface IntrinsicAttributes {
+      key?: string | number
+    }
+  }
+}
+
+export {}