# Copyright 2026 Gaofeng Fan
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""
Voltage source cell definition with symbol support.

Provides a DC voltage source as a reusable cell with:
- Circuit definition for netlist generation
- Symbol definition for schematic visualization

Usage:
    from analogpy.cells import vsource_cell

    supply = vsource_cell("VDD", dc_voltage=1.8)
    tb.instantiate(supply, "I_VDD", plus=vdd_net, minus=gnd)
"""

from ..circuit import Circuit
from ..devices import vsource


def vsource_cell(
    name: str,
    dc_voltage: float,
    ac_magnitude: float = 0.0,
) -> Circuit:
    """
    Create a DC voltage source cell with explicit ports.

    Ports:
        plus: positive terminal (higher voltage)
        minus: negative terminal (reference, typically ground)

    Args:
        name: Cell name (used in netlist subckt definition)
        dc_voltage: DC voltage value in volts
        ac_magnitude: AC magnitude for AC analysis (default 0.0)

    Returns:
        Circuit object representing the voltage source cell
    """
    cell = Circuit(name, ports=["plus", "minus"])

    plus_net = cell.net("plus")
    minus_net = cell.net("minus")

    params = {"dc": dc_voltage}
    if ac_magnitude:
        params["mag"] = ac_magnitude

    cell.instantiate(vsource, "V0", p=plus_net, n=minus_net, **params)

    return cell


# Symbol configuration for schematic visualization
SYMBOL_CONFIG = {
    "type": "vsource",
    "ports": ["plus", "minus"],
    "port_types": {
        "plus": "POWER",
        "minus": "GROUND",
    },
    "shape": "circle",  # Standard voltage source circle with +/-
    "color": "#006600",  # Green (Cadence style)
}
