"""
Enhanced component management with IndexRegistry integration.

This module provides the Component wrapper and ComponentCollection using the new
BaseCollection infrastructure with centralized index management, lazy rebuilding,
and batch mode support.
"""

import logging
import uuid
from typing import Any, Dict, Iterator, List, Optional, Tuple, Union

from ..core.ic_manager import ICManager
from ..core.types import Point, PinInfo, SchematicPin, SchematicSymbol
from ..library.cache import SymbolDefinition, get_symbol_cache
from ..utils.validation import SchematicValidator, ValidationError, ValidationIssue
from .base import BaseCollection, IndexSpec, ValidationLevel

logger = logging.getLogger(__name__)


class Component:
    """
    Enhanced wrapper for schematic components.

    Provides intuitive access to component properties, pins, and operations
    while maintaining exact format preservation. All property modifications
    automatically notify the parent collection for tracking.
    """

    def __init__(self, symbol_data: SchematicSymbol, parent_collection: "ComponentCollection"):
        """
        Initialize component wrapper.

        Args:
            symbol_data: Underlying symbol data
            parent_collection: Parent collection for modification tracking
        """
        self._data = symbol_data
        self._collection = parent_collection
        self._validator = SchematicValidator()

    # Core properties with validation
    @property
    def uuid(self) -> str:
        """Component UUID (read-only)."""
        return self._data.uuid

    @property
    def reference(self) -> str:
        """Component reference designator (e.g., 'R1', 'U2')."""
        return self._data.reference

    @reference.setter
    def reference(self, value: str):
        """
        Set component reference with validation and duplicate checking.

        Args:
            value: New reference designator

        Raises:
            ValidationError: If reference format is invalid or already exists
        """
        if not self._validator.validate_reference(value):
            raise ValidationError(f"Invalid reference format: {value}")

        # Check for duplicates in parent collection
        if self._collection.get(value) is not None:
            raise ValidationError(f"Reference {value} already exists")

        old_ref = self._data.reference
        self._data.reference = value
        self._collection._update_reference_index(old_ref, value)
        self._collection._mark_modified()
        logger.debug(f"Updated reference: {old_ref} -> {value}")

    @property
    def value(self) -> str:
        """Component value (e.g., '10k', '100nF')."""
        return self._data.value

    @value.setter
    def value(self, value: str):
        """Set component value."""
        old_value = self._data.value
        self._data.value = value
        self._collection._update_value_index(self, old_value, value)
        self._collection._mark_modified()

    @property
    def footprint(self) -> Optional[str]:
        """Component footprint (e.g., 'Resistor_SMD:R_0603_1608Metric')."""
        return self._data.footprint

    @footprint.setter
    def footprint(self, value: Optional[str]):
        """Set component footprint."""
        self._data.footprint = value
        self._collection._mark_modified()

    @property
    def position(self) -> Point:
        """Component position in schematic (mm)."""
        return self._data.position

    @position.setter
    def position(self, value: Union[Point, Tuple[float, float]]):
        """
        Set component position.

        Args:
            value: Position as Point or (x, y) tuple
        """
        if isinstance(value, tuple):
            value = Point(value[0], value[1])
        self._data.position = value
        self._collection._mark_modified()

    @property
    def rotation(self) -> float:
        """Component rotation in degrees (0, 90, 180, or 270)."""
        return self._data.rotation

    @rotation.setter
    def rotation(self, value: float):
        """
        Set component rotation.

        KiCad only supports 0, 90, 180, or 270 degree rotations.

        Args:
            value: Rotation angle in degrees

        Raises:
            ValueError: If rotation is not 0, 90, 180, or 270
        """
        # Normalize rotation to 0-360 range
        normalized = float(value) % 360

        # KiCad only accepts specific angles
        VALID_ROTATIONS = {0, 90, 180, 270}
        if normalized not in VALID_ROTATIONS:
            raise ValueError(
                f"Component rotation must be 0, 90, 180, or 270 degrees. "
                f"Got {value}° (normalized to {normalized}°). "
                f"KiCad does not support arbitrary rotation angles."
            )

        self._data.rotation = normalized
        self._collection._mark_modified()

    @property
    def lib_id(self) -> str:
        """Library identifier (e.g., 'Device:R')."""
        return self._data.lib_id

    @property
    def library(self) -> str:
        """Library name (e.g., 'Device' from 'Device:R')."""
        return self._data.library

    @property
    def symbol_name(self) -> str:
        """Symbol name within library (e.g., 'R' from 'Device:R')."""
        return self._data.symbol_name

    # Properties dictionary
    @property
    def properties(self) -> Dict[str, str]:
        """Dictionary of all component properties."""
        return self._data.properties

    def get_property(self, name: str, default: Optional[str] = None) -> Optional[str]:
        """
        Get property value by name.

        Args:
            name: Property name
            default: Default value if property doesn't exist

        Returns:
            Property value or default
        """
        return self._data.properties.get(name, default)

    def set_property(self, name: str, value: str):
        """
        Set property value with validation.

        Args:
            name: Property name
            value: Property value

        Raises:
            ValidationError: If name or value are not strings
        """
        if not isinstance(name, str) or not isinstance(value, str):
            raise ValidationError("Property name and value must be strings")

        self._data.properties[name] = value
        self._collection._mark_modified()
        logger.debug(f"Set property {self.reference}.{name} = {value}")

    def remove_property(self, name: str) -> bool:
        """
        Remove property by name.

        Args:
            name: Property name to remove

        Returns:
            True if property was removed, False if it didn't exist
        """
        if name in self._data.properties:
            del self._data.properties[name]
            self._collection._mark_modified()
            return True
        return False

    # Pin access
    @property
    def pins(self) -> List[SchematicPin]:
        """List of component pins."""
        return self._data.pins

    def get_pin(self, pin_number: str) -> Optional[SchematicPin]:
        """
        Get pin by number.

        Args:
            pin_number: Pin number to find

        Returns:
            SchematicPin if found, None otherwise
        """
        return self._data.get_pin(pin_number)

    def get_pin_position(self, pin_number: str) -> Optional[Point]:
        """
        Get absolute position of a pin.

        Calculates the pin position accounting for component position,
        rotation, and mirroring.

        Args:
            pin_number: Pin number to find position for

        Returns:
            Absolute pin position in schematic coordinates, or None if pin not found
        """
        return self._data.get_pin_position(pin_number)

    # Component state flags
    @property
    def in_bom(self) -> bool:
        """Whether component appears in bill of materials."""
        return self._data.in_bom

    @in_bom.setter
    def in_bom(self, value: bool):
        """Set BOM inclusion flag."""
        self._data.in_bom = bool(value)
        self._collection._mark_modified()

    @property
    def on_board(self) -> bool:
        """Whether component appears on PCB."""
        return self._data.on_board

    @on_board.setter
    def on_board(self, value: bool):
        """Set board inclusion flag."""
        self._data.on_board = bool(value)
        self._collection._mark_modified()

    # Utility methods
    def move(self, x: float, y: float):
        """
        Move component to absolute position.

        Args:
            x: X coordinate in mm
            y: Y coordinate in mm
        """
        self.position = Point(x, y)

    def translate(self, dx: float, dy: float):
        """
        Translate component by offset.

        Args:
            dx: X offset in mm
            dy: Y offset in mm
        """
        current = self.position
        self.position = Point(current.x + dx, current.y + dy)

    def rotate(self, angle: float):
        """
        Rotate component by angle (cumulative).

        Args:
            angle: Rotation angle in degrees (will be normalized to 0/90/180/270)
        """
        self.rotation = (self.rotation + angle) % 360

    def align_pin(
        self, pin_number: str, target_position: Union[Point, Tuple[float, float]]
    ) -> None:
        """
        Move component so that the specified pin is at the target position.

        This adjusts the component's position to align a specific pin with the
        target coordinates while maintaining the component's current rotation.
        Useful for aligning existing components in horizontal signal flows.

        Args:
            pin_number: Pin number to align (e.g., "1", "2")
            target_position: Desired position for the pin (Point or (x, y) tuple)

        Raises:
            ValueError: If pin_number doesn't exist in the component

        Example:
            # Move resistor so pin 2 is at (150, 100)
            r1 = sch.components.get("R1")
            r1.align_pin("2", (150, 100))

            # Align capacitor pin 1 on same horizontal line
            c1 = sch.components.get("C1")
            c1.align_pin("1", (200, 100))  # Same Y as resistor pin 2
        """
        from ..core.geometry import calculate_position_for_pin

        # Get symbol definition to find the pin's local position
        symbol_def = self.get_symbol_definition()
        if not symbol_def:
            raise ValueError(f"Symbol definition not found for {self.reference} ({self.lib_id})")

        # Find the pin in the symbol definition
        pin_def = None
        for pin in symbol_def.pins:
            if pin.number == pin_number:
                pin_def = pin
                break

        if not pin_def:
            available_pins = [p.number for p in symbol_def.pins]
            raise ValueError(
                f"Pin '{pin_number}' not found in component {self.reference} ({self.lib_id}). "
                f"Available pins: {', '.join(available_pins)}"
            )

        logger.debug(
            f"Aligning {self.reference} pin {pin_number} "
            f"(local position: {pin_def.position}) to target {target_position}"
        )

        # Calculate new component position
        new_position = calculate_position_for_pin(
            pin_local_position=pin_def.position,
            desired_pin_position=target_position,
            rotation=self.rotation,
            mirror=None,  # TODO: Add mirror support when needed
            grid_size=1.27,
        )

        old_position = self.position
        self.position = new_position

        logger.info(
            f"Aligned {self.reference} pin {pin_number} to {target_position}: "
            f"moved from {old_position} to {new_position}"
        )

    def copy_properties_from(self, other: "Component"):
        """
        Copy all properties from another component.

        Args:
            other: Component to copy properties from
        """
        for name, value in other.properties.items():
            self.set_property(name, value)

    def get_symbol_definition(self) -> Optional[SymbolDefinition]:
        """
        Get the symbol definition from library cache.

        Returns:
            SymbolDefinition if found, None otherwise
        """
        cache = get_symbol_cache()
        return cache.get_symbol(self.lib_id)

    def update_from_library(self) -> bool:
        """
        Update component pins and metadata from library definition.

        Returns:
            True if update successful, False if symbol not found
        """
        symbol_def = self.get_symbol_definition()
        if not symbol_def:
            return False

        # Update pins
        self._data.pins = symbol_def.pins.copy()

        # Warn if reference prefix doesn't match
        if not self.reference.startswith(symbol_def.reference_prefix):
            logger.warning(
                f"Reference {self.reference} doesn't match expected prefix {symbol_def.reference_prefix}"
            )

        self._collection._mark_modified()
        return True

    def validate(self) -> List[ValidationIssue]:
        """
        Validate this component.

        Returns:
            List of validation issues (empty if valid)
        """
        return self._validator.validate_component(self._data.__dict__)

    def to_dict(self) -> Dict[str, Any]:
        """
        Convert component to dictionary representation.

        Returns:
            Dictionary with component data
        """
        return {
            "reference": self.reference,
            "lib_id": self.lib_id,
            "value": self.value,
            "footprint": self.footprint,
            "position": {"x": self.position.x, "y": self.position.y},
            "rotation": self.rotation,
            "properties": self.properties.copy(),
            "in_bom": self.in_bom,
            "on_board": self.on_board,
            "pin_count": len(self.pins),
        }

    def __str__(self) -> str:
        """String representation for display."""
        return f"<Component {self.reference}: {self.lib_id} = '{self.value}' @ {self.position}>"

    def __repr__(self) -> str:
        """Detailed representation for debugging."""
        return (
            f"Component(ref='{self.reference}', lib_id='{self.lib_id}', "
            f"value='{self.value}', pos={self.position}, rotation={self.rotation})"
        )


class ComponentCollection(BaseCollection[Component]):
    """
    Collection class for efficient component management using IndexRegistry.

    Provides fast lookup, filtering, and bulk operations with lazy index rebuilding
    and batch mode support. Uses centralized IndexRegistry for managing all indexes
    (UUID, reference, lib_id, value).
    """

    def __init__(
        self,
        components: Optional[List[SchematicSymbol]] = None,
        parent_schematic=None,
        validation_level: ValidationLevel = ValidationLevel.NORMAL,
    ):
        """
        Initialize component collection.

        Args:
            components: Initial list of component data
            parent_schematic: Reference to parent Schematic (for hierarchy context)
            validation_level: Validation level for operations
        """
        # Initialize base collection with validation level
        super().__init__(validation_level=validation_level)

        # Store parent schematic reference for hierarchy context
        self._parent_schematic = parent_schematic

        # Manual indexes for special cases not handled by IndexRegistry
        # (These are maintained separately for complex operations)
        self._lib_id_index: Dict[str, List[Component]] = {}
        self._value_index: Dict[str, List[Component]] = {}

        # Add initial components
        if components:
            with self.batch_mode():
                for comp_data in components:
                    component = Component(comp_data, self)
                    super().add(component)
                    self._add_to_manual_indexes(component)

        logger.debug(f"ComponentCollection initialized with {len(self)} components")

    # BaseCollection abstract method implementations
    def _get_item_uuid(self, item: Component) -> str:
        """Extract UUID from component."""
        return item.uuid

    def _create_item(self, **kwargs) -> Component:
        """
        Create a new component (not typically used directly).

        Use add() method instead for proper component creation.
        """
        raise NotImplementedError("Use add() method to create components")

    def _get_index_specs(self) -> List[IndexSpec]:
        """
        Get index specifications for component collection.

        Returns:
            List of IndexSpec for UUID and reference indexes
        """
        return [
            IndexSpec(
                name="uuid",
                key_func=lambda c: c.uuid,
                unique=True,
                description="UUID index for fast lookups",
            ),
            IndexSpec(
                name="reference",
                key_func=lambda c: c.reference,
                unique=True,
                description="Reference designator index (R1, U2, etc.)",
            ),
        ]

    # Component-specific add method
    def add(
        self,
        lib_id: str,
        reference: Optional[str] = None,
        value: str = "",
        position: Optional[Union[Point, Tuple[float, float]]] = None,
        footprint: Optional[str] = None,
        unit: int = 1,
        rotation: float = 0.0,
        component_uuid: Optional[str] = None,
        **properties,
    ) -> Component:
        """
        Add a new component to the schematic.

        Args:
            lib_id: Library identifier (e.g., "Device:R")
            reference: Component reference (auto-generated if None)
            value: Component value
            position: Component position (auto-placed if None)
            footprint: Component footprint
            unit: Unit number for multi-unit components (1-based)
            rotation: Component rotation in degrees (0, 90, 180, 270)
            component_uuid: Specific UUID for component (auto-generated if None)
            **properties: Additional component properties

        Returns:
            Newly created Component

        Raises:
            ValidationError: If component data is invalid
            LibraryError: If symbol library not found
        """
        # Validate lib_id
        validator = SchematicValidator()
        if not validator.validate_lib_id(lib_id):
            raise ValidationError(f"Invalid lib_id format: {lib_id}")

        # Generate reference if not provided
        if not reference:
            reference = self._generate_reference(lib_id)

        # Validate reference
        if not validator.validate_reference(reference):
            raise ValidationError(f"Invalid reference format: {reference}")

        # Check for duplicate reference
        self._ensure_indexes_current()
        if self._index_registry.has_key("reference", reference):
            raise ValidationError(f"Reference {reference} already exists")

        # Set default position if not provided
        if position is None:
            position = self._find_available_position()
        elif isinstance(position, tuple):
            position = Point(position[0], position[1])

        # Always snap component position to KiCAD grid (1.27mm = 50mil)
        from ..core.geometry import snap_to_grid

        snapped_pos = snap_to_grid((position.x, position.y), grid_size=1.27)
        position = Point(snapped_pos[0], snapped_pos[1])

        logger.debug(
            f"Component {reference} position snapped to grid: ({position.x:.3f}, {position.y:.3f})"
        )

        # Normalize and validate rotation
        rotation = rotation % 360
        VALID_ROTATIONS = {0, 90, 180, 270}
        if rotation not in VALID_ROTATIONS:
            raise ValidationError(
                f"Component rotation must be 0, 90, 180, or 270 degrees. "
                f"Got {rotation}°. KiCad does not support arbitrary rotation angles."
            )

        # Add hierarchy_path if parent schematic has hierarchy context
        if self._parent_schematic and hasattr(self._parent_schematic, "_hierarchy_path"):
            if self._parent_schematic._hierarchy_path:
                properties = dict(properties)
                properties["hierarchy_path"] = self._parent_schematic._hierarchy_path
                logger.debug(
                    f"Setting hierarchy_path for component {reference}: "
                    f"{self._parent_schematic._hierarchy_path}"
                )

        # Create component data
        component_data = SchematicSymbol(
            uuid=component_uuid if component_uuid else str(uuid.uuid4()),
            lib_id=lib_id,
            position=position,
            reference=reference,
            value=value,
            footprint=footprint,
            unit=unit,
            rotation=rotation,
            properties=properties,
        )

        # Get symbol definition and update pins
        from ..core.exceptions import LibraryError

        symbol_cache = get_symbol_cache()
        symbol_def = symbol_cache.get_symbol(lib_id)
        if not symbol_def:
            library_name = lib_id.split(":")[0] if ":" in lib_id else "unknown"
            raise LibraryError(
                f"Symbol '{lib_id}' not found in KiCAD libraries. "
                f"Please verify the library name '{library_name}' and symbol name are correct. "
                f"Common libraries include: Device, Connector_Generic, Regulator_Linear, RF_Module",
                field="lib_id",
                value=lib_id,
            )
        component_data.pins = symbol_def.pins.copy()

        # Create component wrapper
        component = Component(component_data, self)

        # Add to collection (includes IndexRegistry)
        super().add(component)

        # Add to manual indexes (lib_id, value)
        self._add_to_manual_indexes(component)

        logger.info(f"Added component: {reference} ({lib_id})")
        return component

    def add_with_pin_at(
        self,
        lib_id: str,
        pin_number: str,
        pin_position: Union[Point, Tuple[float, float]],
        reference: Optional[str] = None,
        value: str = "",
        rotation: float = 0.0,
        footprint: Optional[str] = None,
        unit: int = 1,
        component_uuid: Optional[str] = None,
        **properties,
    ) -> Component:
        """
        Add component positioned by a specific pin location.

        Instead of specifying the component's center position, this method allows
        you to specify where a particular pin should be placed. This is extremely
        useful for aligning components in horizontal signal flows without manual
        offset calculations.

        Args:
            lib_id: Library identifier (e.g., "Device:R", "Device:C")
            pin_number: Pin number to position (e.g., "1", "2")
            pin_position: Desired position for the specified pin
            reference: Component reference (auto-generated if None)
            value: Component value
            rotation: Component rotation in degrees (0, 90, 180, 270)
            footprint: Component footprint
            unit: Unit number for multi-unit components (1-based)
            component_uuid: Specific UUID for component (auto-generated if None)
            **properties: Additional component properties

        Returns:
            Newly created Component with the specified pin at pin_position

        Raises:
            ValidationError: If component data is invalid
            LibraryError: If symbol library not found
            ValueError: If pin_number doesn't exist in the component

        Example:
            # Place resistor with pin 2 at (150, 100)
            r1 = sch.components.add_with_pin_at(
                lib_id="Device:R",
                pin_number="2",
                pin_position=(150, 100),
                value="10k"
            )

            # Place capacitor with pin 1 aligned on same horizontal line
            c1 = sch.components.add_with_pin_at(
                lib_id="Device:C",
                pin_number="1",
                pin_position=(200, 100),  # Same Y as resistor pin 2
                value="100nF"
            )
        """
        from ..core.exceptions import LibraryError
        from ..core.geometry import calculate_position_for_pin

        # Get symbol definition to find the pin's local position
        symbol_cache = get_symbol_cache()
        symbol_def = symbol_cache.get_symbol(lib_id)
        if not symbol_def:
            library_name = lib_id.split(":")[0] if ":" in lib_id else "unknown"
            raise LibraryError(
                f"Symbol '{lib_id}' not found in KiCAD libraries. "
                f"Please verify the library name '{library_name}' and symbol name are correct. "
                f"Common libraries include: Device, Connector_Generic, Regulator_Linear, RF_Module",
                field="lib_id",
                value=lib_id,
            )

        # Find the pin in the symbol definition
        pin_def = None
        for pin in symbol_def.pins:
            if pin.number == pin_number:
                pin_def = pin
                break

        if not pin_def:
            available_pins = [p.number for p in symbol_def.pins]
            raise ValueError(
                f"Pin '{pin_number}' not found in symbol '{lib_id}'. "
                f"Available pins: {', '.join(available_pins)}"
            )

        logger.debug(
            f"Pin {pin_number} found at local position ({pin_def.position.x}, {pin_def.position.y})"
        )

        # Calculate component position that will place the pin at the desired location
        component_position = calculate_position_for_pin(
            pin_local_position=pin_def.position,
            desired_pin_position=pin_position,
            rotation=rotation,
            mirror=None,  # TODO: Add mirror support when needed
            grid_size=1.27,
        )

        logger.info(
            f"Calculated component position ({component_position.x}, {component_position.y}) "
            f"to place pin {pin_number} at ({pin_position if isinstance(pin_position, Point) else Point(*pin_position)})"
        )

        # Use the regular add() method with the calculated position
        return self.add(
            lib_id=lib_id,
            reference=reference,
            value=value,
            position=component_position,
            footprint=footprint,
            unit=unit,
            rotation=rotation,
            component_uuid=component_uuid,
            **properties,
        )

    def add_ic(
        self,
        lib_id: str,
        reference_prefix: str,
        position: Optional[Union[Point, Tuple[float, float]]] = None,
        value: str = "",
        footprint: Optional[str] = None,
        layout_style: str = "vertical",
        **properties,
    ) -> ICManager:
        """
        Add a multi-unit IC with automatic unit placement.

        Args:
            lib_id: Library identifier for the IC (e.g., "74xx:7400")
            reference_prefix: Base reference (e.g., "U1" → U1A, U1B, etc.)
            position: Base position for auto-layout (auto-placed if None)
            value: IC value (defaults to symbol name)
            footprint: IC footprint
            layout_style: Layout algorithm ("vertical", "grid", "functional")
            **properties: Common properties for all units

        Returns:
            ICManager object for position overrides and management

        Example:
            ic = sch.components.add_ic("74xx:7400", "U1", position=(100, 100))
            ic.place_unit(1, position=(150, 80))  # Override Gate A position
        """
        # Set default position if not provided
        if position is None:
            position = self._find_available_position()
        elif isinstance(position, tuple):
            position = Point(position[0], position[1])

        # Set default value to symbol name if not provided
        if not value:
            value = lib_id.split(":")[-1]  # "74xx:7400" → "7400"

        # Create IC manager for this multi-unit component
        ic_manager = ICManager(lib_id, reference_prefix, position, self)

        # Generate all unit components
        unit_components = ic_manager.generate_components(
            value=value, footprint=footprint, properties=properties
        )

        # Add all units to the collection using batch mode for performance
        with self.batch_mode():
            for component_data in unit_components:
                component = Component(component_data, self)
                super().add(component)
                self._add_to_manual_indexes(component)

        logger.info(
            f"Added multi-unit IC: {reference_prefix} ({lib_id}) with {len(unit_components)} units"
        )

        return ic_manager

    # Remove operations
    def remove(self, reference: str) -> bool:
        """
        Remove component by reference designator.

        Args:
            reference: Component reference to remove (e.g., "R1")

        Returns:
            True if component was removed, False if not found

        Raises:
            TypeError: If reference is not a string
        """
        if not isinstance(reference, str):
            raise TypeError(f"reference must be a string, not {type(reference).__name__}")

        self._ensure_indexes_current()

        # Get component from reference index
        ref_idx = self._index_registry.get("reference", reference)
        if ref_idx is None:
            return False

        component = self._items[ref_idx]

        # Remove from manual indexes
        self._remove_from_manual_indexes(component)

        # Remove from base collection (UUID index)
        super().remove(component.uuid)

        logger.info(f"Removed component: {reference}")
        return True

    def remove_by_uuid(self, component_uuid: str) -> bool:
        """
        Remove component by UUID.

        Args:
            component_uuid: Component UUID to remove

        Returns:
            True if component was removed, False if not found

        Raises:
            TypeError: If UUID is not a string
        """
        if not isinstance(component_uuid, str):
            raise TypeError(f"component_uuid must be a string, not {type(component_uuid).__name__}")

        # Get component from UUID index
        component = self.get_by_uuid(component_uuid)
        if not component:
            return False

        # Remove from manual indexes
        self._remove_from_manual_indexes(component)

        # Remove from base collection
        super().remove(component_uuid)

        logger.info(f"Removed component by UUID: {component_uuid}")
        return True

    def remove_component(self, component: Component) -> bool:
        """
        Remove component by component object.

        Args:
            component: Component object to remove

        Returns:
            True if component was removed, False if not found

        Raises:
            TypeError: If component is not a Component instance
        """
        if not isinstance(component, Component):
            raise TypeError(
                f"component must be a Component instance, not {type(component).__name__}"
            )

        # Check if component exists
        if component.uuid not in self:
            return False

        # Remove from manual indexes
        self._remove_from_manual_indexes(component)

        # Remove from base collection
        super().remove(component.uuid)

        logger.info(f"Removed component: {component.reference}")
        return True

    # Lookup methods
    def get(self, reference: str) -> Optional[Component]:
        """
        Get component by reference designator.

        Args:
            reference: Component reference (e.g., "R1")

        Returns:
            Component if found, None otherwise
        """
        self._ensure_indexes_current()
        ref_idx = self._index_registry.get("reference", reference)
        if ref_idx is not None:
            return self._items[ref_idx]
        return None

    def get_by_uuid(self, component_uuid: str) -> Optional[Component]:
        """
        Get component by UUID.

        Args:
            component_uuid: Component UUID

        Returns:
            Component if found, None otherwise
        """
        return super().get(component_uuid)

    # Filter and search methods
    def filter(self, **criteria) -> List[Component]:
        """
        Filter components by various criteria.

        Supported criteria:
            lib_id: Filter by library ID (exact match)
            value: Filter by value (exact match)
            value_pattern: Filter by value pattern (contains)
            reference_pattern: Filter by reference pattern (regex)
            footprint: Filter by footprint (exact match)
            in_area: Filter by area (tuple of (x1, y1, x2, y2))
            has_property: Filter components that have a specific property

        Args:
            **criteria: Filter criteria

        Returns:
            List of matching components
        """
        results = list(self._items)

        # Apply filters
        if "lib_id" in criteria:
            lib_id = criteria["lib_id"]
            results = [c for c in results if c.lib_id == lib_id]

        if "value" in criteria:
            value = criteria["value"]
            results = [c for c in results if c.value == value]

        if "value_pattern" in criteria:
            pattern = criteria["value_pattern"].lower()
            results = [c for c in results if pattern in c.value.lower()]

        if "reference_pattern" in criteria:
            import re

            pattern = re.compile(criteria["reference_pattern"])
            results = [c for c in results if pattern.match(c.reference)]

        if "footprint" in criteria:
            footprint = criteria["footprint"]
            results = [c for c in results if c.footprint == footprint]

        if "in_area" in criteria:
            x1, y1, x2, y2 = criteria["in_area"]
            results = [c for c in results if x1 <= c.position.x <= x2 and y1 <= c.position.y <= y2]

        if "has_property" in criteria:
            prop_name = criteria["has_property"]
            results = [c for c in results if prop_name in c.properties]

        return results

    def filter_by_type(self, component_type: str) -> List[Component]:
        """
        Filter components by type prefix.

        Args:
            component_type: Type prefix (e.g., 'R' for resistors, 'C' for capacitors)

        Returns:
            List of matching components
        """
        return [
            c for c in self._items if c.symbol_name.upper().startswith(component_type.upper())
        ]

    def in_area(self, x1: float, y1: float, x2: float, y2: float) -> List[Component]:
        """
        Get components within rectangular area.

        Args:
            x1, y1: Top-left corner
            x2, y2: Bottom-right corner

        Returns:
            List of components in area
        """
        return self.filter(in_area=(x1, y1, x2, y2))

    def near_point(
        self, point: Union[Point, Tuple[float, float]], radius: float
    ) -> List[Component]:
        """
        Get components within radius of a point.

        Args:
            point: Center point (Point or (x, y) tuple)
            radius: Search radius in mm

        Returns:
            List of components within radius
        """
        if isinstance(point, tuple):
            point = Point(point[0], point[1])

        results = []
        for component in self._items:
            if component.position.distance_to(point) <= radius:
                results.append(component)
        return results

    def find_pins_by_name(
        self, reference: str, name_pattern: str, case_sensitive: bool = False
    ) -> Optional[List[str]]:
        """
        Find pin numbers matching a name pattern.

        Supports both exact matches and wildcard patterns (e.g., "CLK*", "*IN*").
        By default, matching is case-insensitive for maximum flexibility.

        Args:
            reference: Component reference designator (e.g., "R1", "U2")
            name_pattern: Name pattern to search for (e.g., "VCC", "CLK", "OUT", "CLK*", "*IN*")
            case_sensitive: If False (default), matching is case-insensitive

        Returns:
            List of matching pin numbers (e.g., ["1", "2"]), or None if component not found

        Raises:
            ValueError: If name_pattern is empty

        Example:
            # Find all clock pins
            pins = sch.components.find_pins_by_name("U1", "CLK*")
            # Returns: ["5", "10"] (whatever the clock pins are numbered)

            # Find power pins
            pins = sch.components.find_pins_by_name("U1", "VCC")
            # Returns: ["1", "20"] for a common IC
        """
        import fnmatch

        logger.debug(f"[PIN_DISCOVERY] find_pins_by_name() called for {reference}")
        logger.debug(f"[PIN_DISCOVERY]   Pattern: '{name_pattern}' (case_sensitive={case_sensitive})")

        if not name_pattern:
            raise ValueError("name_pattern cannot be empty")

        # Step 1: Get component
        component = self.get(reference)
        if not component:
            logger.warning(f"[PIN_DISCOVERY] Component not found: {reference}")
            return None

        logger.debug(f"[PIN_DISCOVERY] Found component {reference} ({component.lib_id})")

        # Step 2: Get symbol definition
        symbol_def = component.get_symbol_definition()
        if not symbol_def:
            logger.warning(
                f"[PIN_DISCOVERY] Symbol definition not found for {reference} ({component.lib_id})"
            )
            return None

        logger.debug(
            f"[PIN_DISCOVERY] Symbol has {len(symbol_def.pins)} total pins to search"
        )

        # Step 3: Match pins by name
        matching_pins = []
        search_pattern = name_pattern if case_sensitive else name_pattern.lower()

        for pin in symbol_def.pins:
            pin_name = pin.name if case_sensitive else pin.name.lower()

            # Use fnmatch for wildcard matching
            if fnmatch.fnmatch(pin_name, search_pattern):
                logger.debug(
                    f"[PIN_DISCOVERY]   Pin {pin.number} ({pin.name}) matches pattern '{name_pattern}'"
                )
                matching_pins.append(pin.number)

        logger.info(
            f"[PIN_DISCOVERY] Found {len(matching_pins)} pins matching '{name_pattern}' "
            f"in {reference}: {matching_pins}"
        )
        return matching_pins

    def find_pins_by_type(
        self, reference: str, pin_type: Union[str, "PinType"]
    ) -> Optional[List[str]]:
        """
        Find pin numbers by electrical type.

        Returns all pins of a specific electrical type (e.g., all inputs, all power pins).

        Args:
            reference: Component reference designator (e.g., "R1", "U2")
            pin_type: Electrical type filter. Can be:
                     - String: "input", "output", "passive", "power_in", "power_out", etc.
                     - PinType enum value

        Returns:
            List of matching pin numbers, or None if component not found

        Example:
            # Find all input pins
            pins = sch.components.find_pins_by_type("U1", "input")
            # Returns: ["1", "2", "3"]

            # Find all power pins
            pins = sch.components.find_pins_by_type("U1", "power_in")
            # Returns: ["20", "40"] for a common IC
        """
        from ..core.types import PinType

        logger.debug(f"[PIN_DISCOVERY] find_pins_by_type() called for {reference}")

        # Normalize pin_type to PinType enum
        if isinstance(pin_type, str):
            try:
                pin_type_enum = PinType(pin_type)
                logger.debug(f"[PIN_DISCOVERY]   Type filter: {pin_type}")
            except ValueError:
                logger.error(f"[PIN_DISCOVERY] Invalid pin type: {pin_type}")
                raise ValueError(
                    f"Invalid pin type: {pin_type}. "
                    f"Must be one of: {', '.join(pt.value for pt in PinType)}"
                )
        else:
            pin_type_enum = pin_type
            logger.debug(f"[PIN_DISCOVERY]   Type filter: {pin_type_enum.value}")

        # Step 1: Get component
        component = self.get(reference)
        if not component:
            logger.warning(f"[PIN_DISCOVERY] Component not found: {reference}")
            return None

        logger.debug(f"[PIN_DISCOVERY] Found component {reference} ({component.lib_id})")

        # Step 2: Get symbol definition
        symbol_def = component.get_symbol_definition()
        if not symbol_def:
            logger.warning(
                f"[PIN_DISCOVERY] Symbol definition not found for {reference} ({component.lib_id})"
            )
            return None

        logger.debug(
            f"[PIN_DISCOVERY] Symbol has {len(symbol_def.pins)} total pins to filter"
        )

        # Step 3: Filter pins by type
        matching_pins = []
        for pin in symbol_def.pins:
            if pin.pin_type == pin_type_enum:
                logger.debug(
                    f"[PIN_DISCOVERY]   Pin {pin.number} ({pin.name}) is type {pin_type_enum.value}"
                )
                matching_pins.append(pin.number)

        logger.info(
            f"[PIN_DISCOVERY] Found {len(matching_pins)} pins of type '{pin_type_enum.value}' "
            f"in {reference}: {matching_pins}"
        )
        return matching_pins

    def get_pins_info(self, reference: str) -> Optional[List[PinInfo]]:
        """
        Get comprehensive pin information for a component.

        Returns all pins for the specified component with complete metadata
        including electrical type, shape, absolute position (accounting for
        rotation and mirroring), and orientation.

        Args:
            reference: Component reference designator (e.g., "R1", "U2")

        Returns:
            List of PinInfo objects with complete pin metadata, or None if component not found

        Raises:
            LibraryError: If component's symbol library is not available

        Example:
            pins = sch.components.get_pins_info("U1")
            if pins:
                for pin in pins:
                    print(f"Pin {pin.number}: {pin.name} @ {pin.position}")
                    print(f"  Electrical type: {pin.electrical_type.value}")
                    print(f"  Shape: {pin.shape.value}")
        """
        logger.debug(f"[PIN_DISCOVERY] get_pins_info() called for reference: {reference}")

        # Step 1: Find the component
        component = self.get(reference)
        if not component:
            logger.warning(f"[PIN_DISCOVERY] Component not found: {reference}")
            return None

        logger.debug(f"[PIN_DISCOVERY] Found component {reference} ({component.lib_id})")

        # Step 2: Get symbol definition from library cache
        symbol_def = component.get_symbol_definition()
        if not symbol_def:
            from ..core.exceptions import LibraryError

            lib_id = component.lib_id
            logger.error(
                f"[PIN_DISCOVERY] Symbol library not found for component {reference}: {lib_id}"
            )
            raise LibraryError(
                f"Symbol '{lib_id}' not found in KiCAD libraries. "
                f"Please verify the library name and symbol name are correct.",
                field="lib_id",
                value=lib_id,
            )

        logger.debug(
            f"[PIN_DISCOVERY] Retrieved symbol definition for {reference}: "
            f"{len(symbol_def.pins)} pins"
        )

        # Step 3: Build PinInfo list with absolute positions
        pins_info = []
        for pin in symbol_def.pins:
            logger.debug(
                f"[PIN_DISCOVERY] Processing pin {pin.number} ({pin.name}) "
                f"in local coords: {pin.position}"
            )

            # Get absolute position accounting for component rotation
            absolute_position = component.get_pin_position(pin.number)
            if not absolute_position:
                logger.warning(
                    f"[PIN_DISCOVERY] Could not calculate position for pin {pin.number} on {reference}"
                )
                continue

            logger.debug(
                f"[PIN_DISCOVERY] Pin {pin.number} absolute position: {absolute_position}"
            )

            # Create PinInfo with absolute position
            pin_info = PinInfo(
                number=pin.number,
                name=pin.name,
                position=absolute_position,
                electrical_type=pin.pin_type,
                shape=pin.pin_shape,
                length=pin.length,
                orientation=pin.rotation,  # Note: pin rotation in symbol space
                uuid=f"{component.uuid}:{pin.number}",  # Composite UUID
            )

            logger.debug(
                f"[PIN_DISCOVERY] Created PinInfo for pin {pin.number}: "
                f"type={pin_info.electrical_type.value}, shape={pin_info.shape.value}"
            )

            pins_info.append(pin_info)

        logger.info(
            f"[PIN_DISCOVERY] Successfully retrieved {len(pins_info)} pins for {reference}"
        )
        return pins_info

    # Bulk operations
    def bulk_update(self, criteria: Dict[str, Any], updates: Dict[str, Any]) -> int:
        """
        Update multiple components matching criteria.

        Args:
            criteria: Filter criteria (same as filter method)
            updates: Dictionary of property updates

        Returns:
            Number of components updated

        Example:
            # Update all 10k resistors to 1% tolerance
            count = sch.components.bulk_update(
                criteria={'value': '10k'},
                updates={'properties': {'Tolerance': '1%'}}
            )
        """
        matching = self.filter(**criteria)

        for component in matching:
            for key, value in updates.items():
                if key == "properties" and isinstance(value, dict):
                    # Handle properties dictionary specially
                    for prop_name, prop_value in value.items():
                        component.set_property(prop_name, str(prop_value))
                elif hasattr(component, key) and key not in ["properties"]:
                    setattr(component, key, value)
                else:
                    # Add as custom property
                    component.set_property(key, str(value))

        if matching:
            self._mark_modified()

        logger.info(f"Bulk updated {len(matching)} components")
        return len(matching)

    # Sorting
    def sort_by_reference(self):
        """Sort components by reference designator (in-place)."""
        self._items.sort(key=lambda c: c.reference)
        self._index_registry.mark_dirty()

    def sort_by_position(self, by_x: bool = True):
        """
        Sort components by position (in-place).

        Args:
            by_x: If True, sort by X then Y; if False, sort by Y then X
        """
        if by_x:
            self._items.sort(key=lambda c: (c.position.x, c.position.y))
        else:
            self._items.sort(key=lambda c: (c.position.y, c.position.x))
        self._index_registry.mark_dirty()

    # Validation
    def validate_all(self) -> List[ValidationIssue]:
        """
        Validate all components in collection.

        Returns:
            List of validation issues found
        """
        all_issues = []
        validator = SchematicValidator()

        # Validate individual components
        for component in self._items:
            issues = component.validate()
            all_issues.extend(issues)

        # Validate collection-level rules (e.g., duplicate references)
        self._ensure_indexes_current()
        references = [c.reference for c in self._items]
        if len(references) != len(set(references)):
            # Find duplicates
            seen = set()
            duplicates = set()
            for ref in references:
                if ref in seen:
                    duplicates.add(ref)
                seen.add(ref)

            for ref in duplicates:
                all_issues.append(
                    ValidationIssue(
                        category="reference", message=f"Duplicate reference: {ref}", level="error"
                    )
                )

        return all_issues

    # Statistics
    def get_statistics(self) -> Dict[str, Any]:
        """
        Get collection statistics.

        Returns:
            Dictionary with component statistics
        """
        lib_counts = {}
        value_counts = {}

        for component in self._items:
            # Count by library
            lib = component.library
            lib_counts[lib] = lib_counts.get(lib, 0) + 1

            # Count by value
            value = component.value
            if value:
                value_counts[value] = value_counts.get(value, 0) + 1

        # Get base statistics and extend
        base_stats = super().get_statistics()
        base_stats.update(
            {
                "unique_references": len(self._items),  # After rebuild, should equal item_count
                "libraries_used": len(lib_counts),
                "library_breakdown": lib_counts,
                "most_common_values": sorted(
                    value_counts.items(), key=lambda x: x[1], reverse=True
                )[:10],
            }
        )

        return base_stats

    # Collection interface
    def __getitem__(self, key: Union[int, str]) -> Component:
        """
        Get component by index, UUID, or reference.

        Args:
            key: Integer index, UUID string, or reference string

        Returns:
            Component at the specified location

        Raises:
            KeyError: If UUID or reference not found
            IndexError: If index out of range
            TypeError: If key is invalid type
        """
        if isinstance(key, int):
            # Integer index
            return self._items[key]
        elif isinstance(key, str):
            # Try reference first (most common)
            component = self.get(key)
            if component is not None:
                return component

            # Try UUID
            component = self.get_by_uuid(key)
            if component is not None:
                return component

            raise KeyError(f"Component not found: {key}")
        else:
            raise TypeError(f"Invalid key type: {type(key).__name__}")

    def __contains__(self, item: Union[str, Component]) -> bool:
        """
        Check if reference, UUID, or component exists in collection.

        Args:
            item: Reference string, UUID string, or Component instance

        Returns:
            True if item exists, False otherwise
        """
        if isinstance(item, str):
            # Check reference or UUID
            return self.get(item) is not None or self.get_by_uuid(item) is not None
        elif isinstance(item, Component):
            # Check by UUID
            return item.uuid in self
        else:
            return False

    # Internal helper methods
    def _add_to_manual_indexes(self, component: Component):
        """Add component to manual indexes (lib_id, value)."""
        # Add to lib_id index (non-unique)
        lib_id = component.lib_id
        if lib_id not in self._lib_id_index:
            self._lib_id_index[lib_id] = []
        self._lib_id_index[lib_id].append(component)

        # Add to value index (non-unique)
        value = component.value
        if value:
            if value not in self._value_index:
                self._value_index[value] = []
            self._value_index[value].append(component)

    def _remove_from_manual_indexes(self, component: Component):
        """Remove component from manual indexes (lib_id, value)."""
        # Remove from lib_id index
        lib_id = component.lib_id
        if lib_id in self._lib_id_index:
            self._lib_id_index[lib_id].remove(component)
            if not self._lib_id_index[lib_id]:
                del self._lib_id_index[lib_id]

        # Remove from value index
        value = component.value
        if value and value in self._value_index:
            self._value_index[value].remove(component)
            if not self._value_index[value]:
                del self._value_index[value]

    def _update_reference_index(self, old_ref: str, new_ref: str):
        """
        Update reference index when component reference changes.

        This marks the index as dirty so it will be rebuilt with the new reference.
        """
        self._index_registry.mark_dirty()
        logger.debug(f"Reference index marked dirty: {old_ref} -> {new_ref}")

    def _update_value_index(self, component: Component, old_value: str, new_value: str):
        """Update value index when component value changes."""
        # Remove from old value
        if old_value and old_value in self._value_index:
            self._value_index[old_value].remove(component)
            if not self._value_index[old_value]:
                del self._value_index[old_value]

        # Add to new value
        if new_value:
            if new_value not in self._value_index:
                self._value_index[new_value] = []
            self._value_index[new_value].append(component)

    def _generate_reference(self, lib_id: str) -> str:
        """
        Generate unique reference for component.

        Args:
            lib_id: Library identifier to determine prefix

        Returns:
            Generated reference (e.g., "R1", "U2")
        """
        # Get reference prefix from symbol definition
        symbol_cache = get_symbol_cache()
        symbol_def = symbol_cache.get_symbol(lib_id)
        prefix = symbol_def.reference_prefix if symbol_def else "U"

        # Ensure indexes are current
        self._ensure_indexes_current()

        # Find next available number
        counter = 1
        while self._index_registry.has_key("reference", f"{prefix}{counter}"):
            counter += 1

        return f"{prefix}{counter}"

    def _find_available_position(self) -> Point:
        """
        Find an available position for automatic placement.

        Uses simple grid layout algorithm.

        Returns:
            Point for component placement
        """
        # Simple grid placement - could be enhanced with collision detection
        grid_size = 10.0  # 10mm grid
        max_per_row = 10

        row = len(self._items) // max_per_row
        col = len(self._items) % max_per_row

        return Point(col * grid_size, row * grid_size)

    # Compatibility methods for legacy Schematic integration
    @property
    def modified(self) -> bool:
        """Check if collection has been modified (compatibility)."""
        return self.is_modified

    def mark_saved(self) -> None:
        """Mark collection as saved (reset modified flag)."""
        self.mark_clean()
