@pyreon/kinetic 0.11.0 → 0.11.2

package/src/kinetic/TransitionRenderer.tsx

@@ -0,0 +1,168 @@
+import type { VNode } from "@pyreon/core"
+import { createRef, h, Show } from "@pyreon/core"
+import { watch } from "@pyreon/reactivity"
+import type { CSSProperties, TransitionCallbacks } from "../types"
+import useAnimationEnd from "../useAnimationEnd"
+import { useReducedMotion } from "../useReducedMotion"
+import useTransitionState from "../useTransitionState"
+import { addClasses, mergeRefs, nextFrame, removeClasses } from "../utils"
+import type { KineticConfig } from "./types"
+
+type TransitionRendererProps = {
+  config: KineticConfig
+  htmlProps: Record<string, unknown>
+  show: () => boolean
+  appear?: boolean | undefined
+  unmount?: boolean | undefined
+  timeout?: number | undefined
+  callbacks: Partial<TransitionCallbacks>
+  children: VNode | VNode[]
+}
+
+const applyEnter = (el: HTMLElement, config: KineticConfig) => {
+  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: KineticConfig) => {
+  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,
+  cbs: Partial<TransitionCallbacks>,
+  complete: () => void,
+) => {
+  if (stage === "entering") {
+    cbs.onEnter?.()
+    cbs.onAfterEnter?.()
+    complete()
+  } else if (stage === "leaving") {
+    cbs.onLeave?.()
+    cbs.onAfterLeave?.()
+    complete()
+  }
+}
+
+/**
+ * Renders a single element with CSS transition enter/exit animation.
+ * Uses h(config.tag) — no cloneElement needed.
+ */
+const TransitionRenderer = ({
+  config,
+  htmlProps,
+  show,
+  appear,
+  unmount,
+  timeout,
+  callbacks,
+  children,
+}: TransitionRendererProps): VNode | null => {
+  const reducedMotion = useReducedMotion()
+  const {
+    stage,
+    ref: stateRef,
+    shouldMount,
+    complete,
+  } = useTransitionState({
+    show,
+    appear: appear ?? config.appear ?? false,
+  })
+
+  const elementRef = createRef<HTMLElement>()
+  const mergedRef = mergeRefs(elementRef, stateRef)
+
+  const effectiveUnmount = unmount ?? config.unmount ?? true
+  const effectiveTimeout = timeout ?? config.timeout ?? 5000
+
+  useAnimationEnd({
+    ref: elementRef,
+    active: () => (stage() === "entering" || stage() === "leaving") && !reducedMotion(),
+    timeout: effectiveTimeout,
+    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, config)
+        return () => cancelAnimationFrame(frameId)
+      }
+
+      if (currentStage === "leaving") {
+        callbacks.onLeave?.()
+        const frameId = applyLeave(el, config)
+        return () => cancelAnimationFrame(frameId)
+      }
+
+      if (currentStage === "entered") {
+        removeClasses(el, config.enter)
+        el.style.transition = ""
+      }
+    },
+    { immediate: true },
+  )
+
+  return (
+    <Show
+      when={shouldMount}
+      fallback={
+        effectiveUnmount
+          ? null
+          : h(
+              config.tag,
+              {
+                ref: mergedRef,
+                ...htmlProps,
+                style: {
+                  ...((htmlProps.style as CSSProperties) ?? {}),
+                  display: "none",
+                },
+              },
+              children,
+            )
+      }
+    >
+      {h(config.tag, { ref: mergedRef, ...htmlProps }, children)}
+    </Show>
+  )
+}
+
+export default TransitionRenderer

package/src/kinetic/createKineticComponent.tsx

@@ -0,0 +1,211 @@
+import type { VNode } from "@pyreon/core"
+import type { CSSProperties, TransitionCallbacks } from "../types"
+import CollapseRenderer from "./CollapseRenderer"
+import GroupRenderer from "./GroupRenderer"
+import StaggerRenderer from "./StaggerRenderer"
+import TransitionRenderer from "./TransitionRenderer"
+import type { ClassConfig, KineticComponent, KineticConfig, KineticMode } from "./types"
+
+/** Keys that are kinetic-specific and should not be forwarded as HTML attrs. */
+const KINETIC_KEYS = new Set([
+  "show",
+  "appear",
+  "unmount",
+  "timeout",
+  "transition",
+  "interval",
+  "reverseLeave",
+  "onEnter",
+  "onAfterEnter",
+  "onLeave",
+  "onAfterLeave",
+])
+
+/**
+ * Core factory. Creates a component that delegates to the appropriate
+ * renderer based on config.mode, then attaches immutable chain methods
+ * via Object.assign.
+ */
+const createKineticComponent = <Tag extends string, Mode extends KineticMode = "transition">(
+  config: KineticConfig,
+): KineticComponent<Tag, Mode> => {
+  const Component = (props: Record<string, unknown>): VNode | null => {
+    // Separate kinetic-specific props from HTML pass-through props
+    const htmlProps: Record<string, unknown> = {}
+    const kineticProps: Record<string, unknown> = {}
+
+    for (const key in props) {
+      if (KINETIC_KEYS.has(key)) {
+        kineticProps[key] = props[key]
+      } else {
+        htmlProps[key] = props[key]
+      }
+    }
+
+    const {
+      show,
+      appear,
+      unmount,
+      timeout,
+      transition,
+      interval,
+      reverseLeave,
+      onEnter,
+      onAfterEnter,
+      onLeave,
+      onAfterLeave,
+    } = kineticProps as {
+      show?: () => boolean
+      appear?: boolean
+      unmount?: boolean
+      timeout?: number
+      transition?: string
+      interval?: number
+      reverseLeave?: boolean
+    } & Partial<TransitionCallbacks>
+
+    const callbacks: Partial<TransitionCallbacks> = {
+      onEnter: onEnter ?? config.onEnter,
+      onAfterEnter: onAfterEnter ?? config.onAfterEnter,
+      onLeave: onLeave ?? config.onLeave,
+      onAfterLeave: onAfterLeave ?? config.onAfterLeave,
+    }
+
+    // Extract children from htmlProps (it's not an HTML attribute)
+    const { children, ...restHtml } = htmlProps
+
+    if (config.mode === "collapse") {
+      return (
+        <CollapseRenderer
+          config={config}
+          htmlProps={restHtml}
+          show={show as () => boolean}
+          appear={appear}
+          timeout={timeout}
+          transition={transition}
+          callbacks={callbacks}
+        >
+          {children as VNode | VNode[]}
+        </CollapseRenderer>
+      )
+    }
+
+    if (config.mode === "stagger") {
+      return (
+        <StaggerRenderer
+          config={config}
+          htmlProps={restHtml}
+          show={show as () => boolean}
+          appear={appear}
+          timeout={timeout}
+          interval={interval}
+          reverseLeave={reverseLeave}
+          callbacks={callbacks}
+        >
+          {children as VNode[]}
+        </StaggerRenderer>
+      )
+    }
+
+    if (config.mode === "group") {
+      return (
+        <GroupRenderer
+          config={config}
+          htmlProps={restHtml}
+          appear={appear}
+          timeout={timeout}
+          callbacks={callbacks}
+        >
+          {children as VNode[]}
+        </GroupRenderer>
+      )
+    }
+
+    // Default: transition mode
+    return (
+      <TransitionRenderer
+        config={config}
+        htmlProps={restHtml}
+        show={show as () => boolean}
+        appear={appear}
+        unmount={unmount}
+        timeout={timeout}
+        callbacks={callbacks}
+      >
+        {children as VNode | VNode[]}
+      </TransitionRenderer>
+    )
+  }
+
+  Component.displayName = `kinetic(${config.tag})`
+
+  // Immutable chain methods — each returns a new component with merged config.
+  return Object.assign(Component, {
+    preset: (preset: Record<string, unknown>) =>
+      createKineticComponent<Tag, Mode>({
+        ...config,
+        ...preset,
+      } as KineticConfig),
+
+    enter: (styles: CSSProperties) =>
+      createKineticComponent<Tag, Mode>({ ...config, enterStyle: styles }),
+
+    enterTo: (styles: CSSProperties) =>
+      createKineticComponent<Tag, Mode>({ ...config, enterToStyle: styles }),
+
+    enterTransition: (value: string) =>
+      createKineticComponent<Tag, Mode>({ ...config, enterTransition: value }),
+
+    leave: (styles: CSSProperties) =>
+      createKineticComponent<Tag, Mode>({ ...config, leaveStyle: styles }),
+
+    leaveTo: (styles: CSSProperties) =>
+      createKineticComponent<Tag, Mode>({ ...config, leaveToStyle: styles }),
+
+    leaveTransition: (value: string) =>
+      createKineticComponent<Tag, Mode>({ ...config, leaveTransition: value }),
+
+    enterClass: ({ active, from, to }: ClassConfig) =>
+      createKineticComponent<Tag, Mode>({
+        ...config,
+        enter: active,
+        enterFrom: from,
+        enterTo: to,
+      }),
+
+    leaveClass: ({ active, from, to }: ClassConfig) =>
+      createKineticComponent<Tag, Mode>({
+        ...config,
+        leave: active,
+        leaveFrom: from,
+        leaveTo: to,
+      }),
+
+    config: (opts: Record<string, unknown>) =>
+      createKineticComponent<Tag, Mode>({
+        ...config,
+        ...opts,
+      } as KineticConfig),
+
+    on: (cbs: Partial<TransitionCallbacks>) =>
+      createKineticComponent<Tag, Mode>({ ...config, ...cbs }),
+
+    collapse: (opts?: { transition?: string }) =>
+      createKineticComponent<Tag, "collapse">({
+        ...config,
+        mode: "collapse",
+        ...opts,
+      }),
+
+    stagger: (opts?: { interval?: number; reverseLeave?: boolean }) =>
+      createKineticComponent<Tag, "stagger">({
+        ...config,
+        mode: "stagger",
+        ...opts,
+      }),
+
+    group: () => createKineticComponent<Tag, "group">({ ...config, mode: "group" }),
+  }) as unknown as KineticComponent<Tag, Mode>
+}
+
+export default createKineticComponent

package/src/kinetic/types.ts

@@ -0,0 +1,149 @@
+import type { ComponentFn, VNodeChild } from "@pyreon/core"
+import type {
+  ClassTransitionProps,
+  CSSProperties,
+  StyleTransitionProps,
+  TransitionCallbacks,
+} from "../types"
+
+// ─── Kinetic Modes ────────────────────────────────────────
+
+export type KineticMode = "transition" | "collapse" | "stagger" | "group"
+
+// ─── Internal Config (accumulated through chaining) ──────
+
+export type KineticConfig = StyleTransitionProps &
+  ClassTransitionProps &
+  TransitionCallbacks & {
+    tag: string
+    mode: KineticMode
+    appear?: boolean | undefined
+    unmount?: boolean | undefined
+    timeout?: number | undefined
+    /** Collapse: CSS transition for height. */
+    transition?: string | undefined
+    /** Stagger: delay between each child in ms. */
+    interval?: number | undefined
+    /** Stagger: reverse order on leave. */
+    reverseLeave?: boolean | undefined
+  }
+
+// ─── Class Config (for .enterClass / .leaveClass) ────────
+
+export type ClassConfig = {
+  active?: string | undefined
+  from?: string | undefined
+  to?: string | undefined
+}
+
+// ─── Mode-specific config options for .config() ──────────
+
+export type TransitionConfigOpts = {
+  appear?: boolean | undefined
+  unmount?: boolean | undefined
+  timeout?: number | undefined
+}
+
+export type CollapseConfigOpts = {
+  appear?: boolean | undefined
+  timeout?: number | undefined
+  transition?: string | undefined
+}
+
+export type StaggerConfigOpts = {
+  appear?: boolean | undefined
+  timeout?: number | undefined
+  interval?: number | undefined
+  reverseLeave?: boolean | undefined
+}
+
+export type GroupConfigOpts = {
+  appear?: boolean | undefined
+  timeout?: number | undefined
+}
+
+// ─── Mode-specific component props ───────────────────────
+
+export type KineticTransitionProps<_Tag extends string> = Record<string, unknown> & {
+  show: () => boolean
+  appear?: boolean | undefined
+  unmount?: boolean | undefined
+  timeout?: number | undefined
+  children?: VNodeChild | undefined
+} & Partial<TransitionCallbacks>
+
+export type KineticCollapseProps<_Tag extends string> = Record<string, unknown> & {
+  show: () => boolean
+  appear?: boolean | undefined
+  timeout?: number | undefined
+  transition?: string | undefined
+  children?: VNodeChild | undefined
+} & Partial<TransitionCallbacks>
+
+export type KineticStaggerProps<_Tag extends string> = Record<string, unknown> & {
+  show: () => boolean
+  appear?: boolean | undefined
+  timeout?: number | undefined
+  interval?: number | undefined
+  reverseLeave?: boolean | undefined
+  children: VNodeChild
+} & Partial<TransitionCallbacks>
+
+export type KineticGroupProps<_Tag extends string> = Record<string, unknown> & {
+  appear?: boolean | undefined
+  timeout?: number | undefined
+  children: VNodeChild
+} & Partial<TransitionCallbacks>
+
+// ─── Conditional props based on mode ─────────────────────
+
+export type KineticComponentProps<
+  Tag extends string,
+  Mode extends KineticMode,
+> = Mode extends "collapse"
+  ? KineticCollapseProps<Tag>
+  : Mode extends "stagger"
+    ? KineticStaggerProps<Tag>
+    : Mode extends "group"
+      ? KineticGroupProps<Tag>
+      : KineticTransitionProps<Tag>
+
+// ─── Conditional config opts based on mode ───────────────
+
+type ConfigOpts<Mode extends KineticMode> = Mode extends "collapse"
+  ? CollapseConfigOpts
+  : Mode extends "stagger"
+    ? StaggerConfigOpts
+    : Mode extends "group"
+      ? GroupConfigOpts
+      : TransitionConfigOpts
+
+// ─── Chain methods ───────────────────────────────────────
+
+export type KineticChain<Tag extends string, Mode extends KineticMode> = {
+  displayName: string
+  preset: (preset: StyleTransitionProps & ClassTransitionProps) => KineticComponent<Tag, Mode>
+  enter: (styles: CSSProperties) => KineticComponent<Tag, Mode>
+  enterTo: (styles: CSSProperties) => KineticComponent<Tag, Mode>
+  enterTransition: (value: string) => KineticComponent<Tag, Mode>
+  leave: (styles: CSSProperties) => KineticComponent<Tag, Mode>
+  leaveTo: (styles: CSSProperties) => KineticComponent<Tag, Mode>
+  leaveTransition: (value: string) => KineticComponent<Tag, Mode>
+  enterClass: (opts: ClassConfig) => KineticComponent<Tag, Mode>
+  leaveClass: (opts: ClassConfig) => KineticComponent<Tag, Mode>
+  config: (opts: ConfigOpts<Mode>) => KineticComponent<Tag, Mode>
+  on: (callbacks: Partial<TransitionCallbacks>) => KineticComponent<Tag, Mode>
+  collapse: (opts?: CollapseConfigOpts) => KineticComponent<Tag, "collapse">
+  stagger: (opts?: {
+    interval?: number | undefined
+    reverseLeave?: boolean | undefined
+  }) => KineticComponent<Tag, "stagger">
+  group: () => KineticComponent<Tag, "group">
+}
+
+// ─── The full kinetic component: renderable + chainable ───
+
+export type KineticComponent<
+  Tag extends string,
+  Mode extends KineticMode = "transition",
+> = ComponentFn<KineticComponentProps<Tag, Mode>> & KineticChain<Tag, Mode>

package/src/kinetic.ts

@@ -0,0 +1,25 @@
+import createKineticComponent from "./kinetic/createKineticComponent"
+import type { KineticComponent } from "./kinetic/types"
+
+/**
+ * Creates a reusable animated component via immutable chaining.
+ *
+ * @example
+ * ```tsx
+ * // Transition (default)
+ * const FadeDiv = kinetic('div').preset(fade)
+ *
+ * // Collapse
+ * const Accordion = kinetic('div').collapse()
+ *
+ * // Stagger
+ * const StaggerList = kinetic('ul').preset(slideUp).stagger({ interval: 50 })
+ *
+ * // Group (key-based enter/exit)
+ * const AnimatedList = kinetic('ul').preset(fade).group()
+ * ```
+ */
+const kinetic = <Tag extends string>(tag: Tag): KineticComponent<Tag, "transition"> =>
+  createKineticComponent<Tag, "transition">({ tag, mode: "transition" })
+
+export default kinetic

package/src/presets.ts

@@ -0,0 +1,66 @@
+import type { ClassTransitionProps, StyleTransitionProps } from "./types"
+
+export type Preset = StyleTransitionProps & ClassTransitionProps
+
+export const fade: Preset = {
+  enterStyle: { opacity: 0 },
+  enterToStyle: { opacity: 1 },
+  enterTransition: "opacity 300ms ease-out",
+  leaveStyle: { opacity: 1 },
+  leaveToStyle: { opacity: 0 },
+  leaveTransition: "opacity 200ms ease-in",
+}
+
+export const scaleIn: Preset = {
+  enterStyle: { opacity: 0, transform: "scale(0.95)" },
+  enterToStyle: { opacity: 1, transform: "scale(1)" },
+  enterTransition: "opacity 300ms ease-out, transform 300ms ease-out",
+  leaveStyle: { opacity: 1, transform: "scale(1)" },
+  leaveToStyle: { opacity: 0, transform: "scale(0.95)" },
+  leaveTransition: "opacity 200ms ease-in, transform 200ms ease-in",
+}
+
+export const slideUp: Preset = {
+  enterStyle: { opacity: 0, transform: "translateY(16px)" },
+  enterToStyle: { opacity: 1, transform: "translateY(0)" },
+  enterTransition: "opacity 300ms ease-out, transform 300ms ease-out",
+  leaveStyle: { opacity: 1, transform: "translateY(0)" },
+  leaveToStyle: { opacity: 0, transform: "translateY(16px)" },
+  leaveTransition: "opacity 200ms ease-in, transform 200ms ease-in",
+}
+
+export const slideDown: Preset = {
+  enterStyle: { opacity: 0, transform: "translateY(-16px)" },
+  enterToStyle: { opacity: 1, transform: "translateY(0)" },
+  enterTransition: "opacity 300ms ease-out, transform 300ms ease-out",
+  leaveStyle: { opacity: 1, transform: "translateY(0)" },
+  leaveToStyle: { opacity: 0, transform: "translateY(-16px)" },
+  leaveTransition: "opacity 200ms ease-in, transform 200ms ease-in",
+}
+
+export const slideLeft: Preset = {
+  enterStyle: { opacity: 0, transform: "translateX(16px)" },
+  enterToStyle: { opacity: 1, transform: "translateX(0)" },
+  enterTransition: "opacity 300ms ease-out, transform 300ms ease-out",
+  leaveStyle: { opacity: 1, transform: "translateX(0)" },
+  leaveToStyle: { opacity: 0, transform: "translateX(16px)" },
+  leaveTransition: "opacity 200ms ease-in, transform 200ms ease-in",
+}
+
+export const slideRight: Preset = {
+  enterStyle: { opacity: 0, transform: "translateX(-16px)" },
+  enterToStyle: { opacity: 1, transform: "translateX(0)" },
+  enterTransition: "opacity 300ms ease-out, transform 300ms ease-out",
+  leaveStyle: { opacity: 1, transform: "translateX(0)" },
+  leaveToStyle: { opacity: 0, transform: "translateX(-16px)" },
+  leaveTransition: "opacity 200ms ease-in, transform 200ms ease-in",
+}
+
+export const presets = {
+  fade,
+  scaleIn,
+  slideUp,
+  slideDown,
+  slideLeft,
+  slideRight,
+} as const