namespace Project_Periodensystem.Model
{
    /// <summary>
    /// Repräsentiert ein chemisches Element im Periodensystem
    /// 
    /// ZWECK UND DATENMODELL:
    /// - Zentrale Datenstruktur für alle Elementinformationen
    /// - Kapselt alle relevanten chemischen Eigenschaften
    /// - Bildet die Grundlage für Periodensystem-Darstellung und -Berechnungen
    /// 
    /// DESIGN PRINCIPLES:
    /// - Data Transfer Object (DTO): Reine Datenklasse ohne Geschäftslogik
    /// - Immutable nach Konstruktion: Alle Properties haben nur Setter (könnten readonly sein)
    /// - Rich Object: Enthält alle relevanten Eigenschaften in einer Klasse
    /// 
    /// C# KONZEPTE:
    /// - Auto-Properties: { get; set; } automatische Getter/Setter
    /// - Constructor mit mehreren Parametern: Vollständige Initialisierung
    /// - Value Types (int, double): Primitive Datentypen für Zahlen
    /// - Reference Types (string): Referenzdatentypen für Text
    /// 
    /// VERWENDUNG IM PERIODENSYSTEM:
    /// - Gespeichert in List&lt;Element&gt; Collections
    /// - Sortiert nach AtomicNumber für Periodensystem-Darstellung
    /// - Gruppiert nach Series für chemische Klassifizierung
    /// - Positioniert nach Row/Column im UI-Grid
    /// </summary>
    public class Element
    {
        // ===== IDENTIFIKATIONS-EIGENSCHAFTEN =====
        
        /// <summary>
        /// Ordnungszahl (Protonenzahl) des Elements
        /// 
        /// CHEMISCHE BEDEUTUNG:
        /// - Eindeutige Identifikation jedes Elements (1-118)
        /// - Bestimmt Position im Periodensystem
        /// - Entspricht der Anzahl Protonen im Atomkern
        /// 
        /// BEISPIELE:
        /// - 1 = Wasserstoff (H)
        /// - 6 = Kohlenstoff (C)
        /// - 79 = Gold (Au)
        /// </summary>
        public int AtomicNumber { get; set; }

        /// <summary>
        /// Chemisches Symbol (Kurzbezeichnung) des Elements
        /// 
        /// KONVENTIONEN:
        /// - 1-2 Buchstaben, erster Buchstabe groß
        /// - Oft lateinischen/griechischen Ursprungs
        /// - International standardisiert (IUPAC)
        /// 
        /// BEISPIELE:
        /// - "H" = Hydrogen (Wasserstoff)
        /// - "Au" = Aurum (Gold)
        /// - "Fe" = Ferrum (Eisen)
        /// </summary>
        public string Symbol { get; set; }

        /// <summary>
        /// Vollständiger wissenschaftlicher Name des Elements
        /// 
        /// NAMENSGEBUNG:
        /// - Offizielle IUPAC-Bezeichnung
        /// - Meist englische Namen in der internationalen Wissenschaft
        /// - Historische, mythologische oder wissenschaftliche Herkunft
        /// 
        /// BEISPIELE:
        /// - "Hydrogen" (griechisch: Wasser-bildend)
        /// - "Californium" (nach Kalifornien benannt)
        /// - "Einstein­ium" (nach Albert Einstein)
        /// </summary>
        public string ElementName { get; set; }

        // ===== PHYSIKALISCHE EIGENSCHAFTEN =====
        
        /// <summary>
        /// Relative Atommasse in atomaren Masseneinheiten (u)
        /// 
        /// CHEMISCHE BEDEUTUNG:
        /// - Durchschnittliche Masse aller Isotope eines Elements
        /// - Gewichtet nach natürlicher Häufigkeit der Isotope
        /// - Basis für stöchiometrische Berechnungen
        /// 
        /// EINHEIT: u (atomic mass unit)
        /// - 1 u ≈ 1.66054 × 10⁻²⁷ kg
        /// - Relative Skala (Kohlenstoff-12 = 12.000 u)
        /// 
        /// BEISPIELE:
        /// - Wasserstoff: ~1.008 u
        /// - Kohlenstoff: ~12.011 u
        /// - Uran: ~238.029 u
        /// </summary>
        public double AtomicWeight { get; set; }

        /// <summary>
        /// Elektronegativität nach Pauling-Skala
        /// 
        /// CHEMISCHE BEDEUTUNG:
        /// - Fähigkeit eines Atoms, Bindungselektronen anzuziehen
        /// - Bestimmt Art der chemischen Bindung (ionisch vs. kovalent)
        /// - Wichtig für Vorhersage chemischer Reaktionen
        /// 
        /// PAULING-SKALA:
        /// - Dimensionslose Größe von 0.7 bis 4.0
        /// - Fluor hat den höchsten Wert (4.0)
        /// - Trends: Steigt in Perioden von links nach rechts
        /// 
        /// BEISPIELE:
        /// - Fluor: 4.0 (höchste Elektronegativität)
        /// - Sauerstoff: 3.5
        /// - Wasserstoff: 2.1
        /// - Cäsium: 0.7 (niedrigste)
        /// </summary>
        public double Electronegativity { get; set; }

        /// <summary>
        /// Dichte bei Standardbedingungen in g/cm³
        /// 
        /// PHYSIKALISCHE BEDEUTUNG:
        /// - Masse pro Volumeneinheit
        /// - Abhängig von Atomgröße und Kristallstruktur
        /// - Wichtig für technische Anwendungen
        /// 
        /// TRENDS IM PERIODENSYSTEM:
        /// - Generell zunehmend mit steigender Ordnungszahl
        /// - Maximum bei Osmium (~22.6 g/cm³)
        /// - Gase haben sehr geringe Dichten
        /// 
        /// BEISPIELE:
        /// - Wasserstoff (Gas): ~0.0000899 g/cm³
        /// - Wasser (Referenz): 1.0 g/cm³
        /// - Gold: ~19.3 g/cm³
        /// - Osmium: ~22.6 g/cm³ (dichtestes Element)
        /// </summary>
        public double Density { get; set; }

        // ===== KLASSIFIKATIONS-EIGENSCHAFTEN =====
        
        /// <summary>
        /// Chemische Serie/Gruppe des Elements
        /// 
        /// KLASSIFIKATION:
        /// - Gruppiert Elemente nach ähnlichen chemischen Eigenschaften
        /// - Basis für Periodensystem-Farben und -Organisation
        /// - Ermöglicht Vorhersage chemischen Verhaltens
        /// 
        /// WICHTIGE SERIEN:
        /// - "Alkali metal": Li, Na, K, Rb, Cs, Fr (sehr reaktiv)
        /// - "Noble gas": He, Ne, Ar, Kr, Xe, Rn (inert)
        /// - "Halogen": F, Cl, Br, I, At (7 Valenzelektronen)
        /// - "Transition metal": Fe, Cu, Au, etc. (d-Block)
        /// - "Lanthanoid": Seltene Erden (f-Block)
        /// 
        /// UI-VERWENDUNG:
        /// - Farbkodierung im Periodensystem
        /// - Filterung und Gruppierung
        /// - Tooltip-Informationen
        /// </summary>
        public string Series { get; set; }
        
        // ===== POSITIONIERUNGS-EIGENSCHAFTEN =====
        
        /// <summary>
        /// Zeile (Periode) im Periodensystem
        /// 
        /// CHEMISCHE BEDEUTUNG:
        /// - Entspricht der Anzahl Elektronenschalen
        /// - Bestimmt vertikale Position im Periodensystem
        /// - 1-7 für natürliche Elemente
        /// 
        /// TRENDS:
        /// - Atomradius nimmt innerhalb einer Periode ab
        /// - Ionisierungsenergie steigt innerhalb einer Periode
        /// </summary>
        public int Row { get; set; }
        
        /// <summary>
        /// Spalte (Gruppe) im Periodensystem
        /// 
        /// CHEMISCHE BEDEUTUNG:
        /// - Entspricht der Anzahl Valenzelektronen (vereinfacht)
        /// - Bestimmt horizontale Position im Periodensystem
        /// - 1-18 nach IUPAC-Nummerierung
        /// 
        /// TRENDS:
        /// - Elemente derselben Gruppe haben ähnliche Eigenschaften
        /// - Chemische Reaktivität folgt Gruppenmustern
        /// </summary>
        public int Column { get; set; }

        // ===== KONSTRUKTOR =====
        
        /// <summary>
        /// Vollständiger Konstruktor für die Erstellung eines Element-Objekts
        /// 
        /// ZWECK:
        /// - Stellt sicher, dass alle Eigenschaften beim Erstellen gesetzt werden
        /// - Verhindert unvollständig initialisierte Element-Objekte
        /// - Ermöglicht direkte Erstellung aus Datenquellen (CSV, JSON, Database)
        /// 
        /// C# KONZEPTE:
        /// - Constructor Overloading: Könnte mehrere Konstruktoren haben
        /// - Parameter Validation: Könnte Validierung der Eingabewerte enthalten
        /// - Immutable Object: Nach Konstruktion unveränderlich (wenn Properties readonly wären)
        /// 
        /// PARAMETER:
        /// - Alle 9 Eigenschaften müssen beim Erstellen angegeben werden
        /// - Reihenfolge entspricht logischer Gruppierung (ID, Name, Physik, Position)
        /// 
        /// VERWENDUNG:
        /// var hydrogen = new Element(1, "H", "Hydrogen", 1.008, 2.1, 0.0000899, "Nonmetal", 1, 1);
        /// </summary>
        public Element(int atomicNumber, string symbol, string elementname, double atomicWeight, 
                       double electronegativity, double density, string series, int row, int column)
        {
            // Eigenschafts-Zuweisungen mit Selbst-Dokumentation
            AtomicNumber = atomicNumber;         // Eindeutige Identifikation
            Symbol = symbol;                     // Kurze chemische Bezeichnung
            ElementName = elementname;           // Vollständiger Name
            AtomicWeight = atomicWeight;         // Relative Atommasse
            Electronegativity = electronegativity; // Bindungsverhalten
            Density = density;                   // Physikalische Eigenschaft
            Series = series;                     // Chemische Klassifikation
            Row = row;                          // Periodensystem-Position vertikal
            Column = column;                    // Periodensystem-Position horizontal
        }
    }
}