"""Stimulus timeline interfaces for NeuroWeave."""

from __future__ import annotations

from typing import Any

from .timeline_events import TimelineEvents
from .timeline_segments import TimelineSegments
from .timeline_signal import TimelineSignal


class StimulusTimeline:
    """Central container storing time-aligned stimulus information.

    Parameters
    ----------
    duration : float
        Total duration of the timeline in seconds.
    sampling_rate : float
        Sampling rate associated with the timeline.
    metadata : dict[str, Any] | None, optional
        Additional metadata describing the stimulus timeline.
    """

    def __init__(
        self,
        duration: float,
        sampling_rate: float,
        metadata: dict[str, Any] | None = None,
    ) -> None:
        self.duration = duration
        self.sampling_rate = sampling_rate
        self.signals: list[TimelineSignal] = []
        self.events: list[TimelineEvents] = []
        self.segments: list[TimelineSegments] = []
        self.metadata = metadata if metadata is not None else {}

    def add_signal(self, signal: TimelineSignal) -> None:
        """Add a continuous signal to the timeline.

        Parameters
        ----------
        signal : TimelineSignal
            Continuous stimulus signal to add.
        """

        raise NotImplementedError()

    def add_events(self, events: TimelineEvents) -> None:
        """Add an event stream to the timeline.

        Parameters
        ----------
        events : TimelineEvents
            Event stream to add.
        """

        raise NotImplementedError()

    def add_segments(self, segments: TimelineSegments) -> None:
        """Add temporal segment annotations to the timeline.

        Parameters
        ----------
        segments : TimelineSegments
            Segment annotations to add.
        """

        raise NotImplementedError()

    def list_signals(self) -> list[str]:
        """Return names of stored continuous signals.

        Returns
        -------
        list[str]
            Signal names in the timeline.
        """

        raise NotImplementedError()

    def list_events(self) -> list[str]:
        """Return names of stored event streams.

        Returns
        -------
        list[str]
            Event stream names in the timeline.
        """

        raise NotImplementedError()

    def summary(self) -> str:
        """Summarize the stimulus timeline.

        Returns
        -------
        str
            Human-readable overview of timeline contents.
        """

        raise NotImplementedError()
