{"version":3,"file":"useTimelineEvent.mjs","names":[],"sources":["../../../src/hooks/core/useTimelineEvent.ts"],"sourcesContent":["import { useTimelineEngine } from '#react/hooks/core/useTimelineEngine';\nimport type { EngineEventMap } from '@techsquidtv/canvas-timeline-core';\nimport { useEffect, useRef } from 'react';\n/**\n * Callback signature for a typed TimelineEngine event subscription.\n *\n * @template EventName - Timeline engine event name from `EngineEventMap`.\n *\n * @see {@link useTimelineEvent}\n * @see {@link https://canvastimeline.com/docs/events-and-lifecycle | Events and lifecycle}\n */\nexport type TimelineEventHandler<EventName extends keyof EngineEventMap> = (\n  payload: EngineEventMap[EventName]\n) => void;\n\n/** Options for `useTimelineEvent`. */\nexport interface TimelineEventOptions {\n  /** Whether the subscription should be active. Defaults to true. */\n  enabled?: boolean;\n}\n\n/**\n * Subscribes to a typed TimelineEngine event with a React-safe latest handler.\n *\n * @remarks\n *\n * The hook keeps the event subscription stable while updating the callback ref\n * every render, avoiding stale closures without resubscribing for handler-only\n * changes. Use it for low-level integration work such as analytics, custom\n * status panels, or imperative bridges. Prefer focused hooks such as\n * {@link useTimelinePlayheadTime} or {@link useTimelineClipDropFeedback} when a\n * public hook already exists for the state you need. Events with `void`\n * payloads can still use zero-argument handlers.\n *\n * @param eventName - TimelineEngine event name to subscribe to.\n * @param handler - Callback invoked with the typed event payload.\n * @param options - Optional subscription controls.\n * @template EventName - Timeline engine event name from `EngineEventMap`.\n * @returns Nothing; the subscription is managed for the component lifetime.\n *\n * @example\n * ```tsx\n * import { useState } from 'react';\n * import { useTimelineEvent } from '@techsquidtv/canvas-timeline-react';\n *\n * export function PlaybackRateReadout() {\n *   const [rate, setRate] = useState(1);\n *\n *   useTimelineEvent('playback:rate', setRate);\n *\n *   return <span>{rate}x</span>;\n * }\n * ```\n *\n * @see {@link https://canvastimeline.com/docs/events-and-lifecycle | Events and lifecycle}\n */\nexport function useTimelineEvent<EventName extends keyof EngineEventMap>(\n  eventName: EventName,\n  handler: TimelineEventHandler<EventName>,\n  options: TimelineEventOptions = {}\n) {\n  const { enabled = true } = options;\n  const engine = useTimelineEngine();\n  const handlerRef = useRef(handler);\n\n  useEffect(() => {\n    handlerRef.current = handler;\n  }, [handler]);\n\n  useEffect(() => {\n    if (!enabled) {\n      return;\n    }\n\n    return engine.on(eventName, (payload) => {\n      handlerRef.current(payload);\n    });\n  }, [enabled, engine, eventName]);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwDA,SAAgB,iBACd,WACA,SACA,UAAgC,CAAC,GACjC;CACA,MAAM,EAAE,UAAU,SAAS;CAC3B,MAAM,SAAS,kBAAkB;CACjC,MAAM,aAAa,OAAO,OAAO;CAEjC,gBAAgB;EACd,WAAW,UAAU;CACvB,GAAG,CAAC,OAAO,CAAC;CAEZ,gBAAgB;EACd,IAAI,CAAC,SACH;EAGF,OAAO,OAAO,GAAG,YAAY,YAAY;GACvC,WAAW,QAAQ,OAAO;EAC5B,CAAC;CACH,GAAG;EAAC;EAAS;EAAQ;CAAS,CAAC;AACjC"}