"""Component utility functions.

Deprecated: prefer :mod:`jbom.common.component_classification`.

This module remains as a compatibility shim for existing imports.
"""

from __future__ import annotations

from typing import Optional

from jbom.common.component_classification import (
    get_component_type as _get_component_type,
)


def derive_package_from_footprint(footprint: str) -> str:
    """Derive a best-effort package name from a KiCad footprint identifier.

    Strips the library prefix (e.g. ``SPCoast:0603-RES`` -> ``0603-RES``).
    Returns the footprint as-is if no colon separator is present.

    Args:
        footprint: KiCad footprint string (may include library prefix)

    Returns:
        Package name string, empty string if footprint is empty
    """
    if not footprint:
        return ""
    if ":" in footprint:
        return footprint.split(":", 1)[-1]
    return footprint


def get_component_type(
    lib_id: str,
    footprint: str = "",
    reference: str = "",
    *,
    description: str = "",
    keywords: str = "",
) -> Optional[str]:
    """Determine component type from library ID, footprint, and reference designator.

    Args:
        lib_id: KiCad library ID (e.g., "Device:R")
        footprint: Component footprint (e.g., "R_0603")
        reference: KiCad reference designator (e.g., "R1", "U3")
        description: KiCad component Description property (optional).
        keywords: KiCad component Keywords property (optional).

    Returns:
        Component type string or None if unknown
    """

    return _get_component_type(
        lib_id=lib_id,
        footprint=footprint,
        reference=reference,
        description=description,
        keywords=keywords,
    )
