"""Clipes conectados (lanes acima/abaixo da spine).

Extraído de writer.py — ver fcpxml/writer/__init__.py para o conjunto.
"""

import xml.etree.ElementTree as ET
from typing import Optional


class ConnectedMixin:
    """Clipes conectados (lanes acima/abaixo da spine)."""

    # CONNECTED CLIP OPERATIONS (v0.5.0)
    # ========================================================================

    def add_connected_clip(
        self,
        parent_clip_id: str,
        asset_id: Optional[str] = None,
        asset_name: Optional[str] = None,
        offset: str = "0s",
        duration: Optional[str] = None,
        lane: int = 1,
    ) -> ET.Element:
        """Add a connected clip (B-roll, title, audio) to an existing timeline clip.

        Args:
            parent_clip_id: Name/ID of the clip to attach to
            asset_id: Asset reference ID
            asset_name: Asset name (alternative to asset_id)
            offset: Position relative to parent clip start
            duration: Duration of connected clip (default: full asset)
            lane: Lane number (positive=above, negative=below)

        Returns:
            The created connected clip element
        """
        parent = self._require_clip(parent_clip_id)
        asset, asset_id = self._resolve_asset(asset_id, asset_name)
        clip_duration, source_start = self._resolve_clip_duration(asset, duration)

        new_clip = self._make_asset_clip(
            asset_id, asset.get('name', 'Untitled'),
            self._parse_time(offset), source_start, clip_duration,
            parent=parent, lane=str(lane),
        )
        return new_clip

    # ========================================================================