Prefer KiCad style-1 pin names for symbol variants (#553)

Fixes regression introduced in 1587a79 (unnamed-pin fallback unification).

Author: akhilles

CHANGELOG.md

@@ -29,6 +29,7 @@ and this project adheres to Semantic Versioning (https://semver.org/spec/v2.0.0.
 ### Fixed
 
 - Standardized KiCad unnamed-pin handling: empty/placeholder names now fall back to pin numbers in both import and runtime symbol loading, fixing `Unknown pin name` errors for imported components.
+- KiCad symbol variant parsing now selects one style per unit using named-pin coverage (tie: lowest style index), avoiding pin-name overrides while supporting `_N_0` symbols.
 
 ## [0.3.42] - 2026-02-13
 

crates/pcb-eda/src/kicad/symbol.rs

@@ -2,7 +2,8 @@ use crate::{Part, Pin, PinAt, Symbol};
 use anyhow::Result;
 use pcb_sexpr::{parse, Sexpr, SexprKind};
 use serde::Serialize;
-use std::collections::HashMap;
+use std::cmp::Reverse;
+use std::collections::{BTreeMap, HashMap};
 use std::fs;
 use std::path::Path;
 use std::str::FromStr;
@@ -147,6 +148,7 @@ pub(super) fn parse_symbol(symbol_data: &[Sexpr]) -> Result<KicadSymbol> {
         raw_sexp: Some(Sexpr::list(symbol_data.to_vec())),
         ..Default::default()
     };
+    let mut nested_pin_groups: BTreeMap<u32, Vec<NestedStylePins>> = BTreeMap::new();
 
     for prop in &symbol_data[2..] {
         if let SexprKind::List(prop_list) = &prop.kind {
@@ -168,31 +170,82 @@ pub(super) fn parse_symbol(symbol_data: &[Sexpr]) -> Result<KicadSymbol> {
                         }
                     }
                     _ if prop_name.starts_with("symbol") => {
-                        // This is the nested symbol section which may contain pins
-                        parse_symbol_section(&mut symbol, prop_list);
+                        // Nested symbol sections contain unit/style-specific graphics + pins.
+                        let (unit, style) = nested_symbol_unit_style(prop_list);
+                        let pins = parse_symbol_section(prop_list);
+                        let named_pin_count = pins.iter().filter(|p| is_named_pin(p)).count();
+                        nested_pin_groups
+                            .entry(unit)
+                            .or_default()
+                            .push(NestedStylePins {
+                                style,
+                                named_pin_count,
+                                pins,
+                            });
                     }
                     _ => {}
                 }
             }
         }
     }
 
+    for (_unit, style_candidates) in nested_pin_groups {
+        if let Some(best) = style_candidates
+            .into_iter()
+            .max_by_key(|c| (c.named_pin_count, Reverse(c.style)))
+        {
+            symbol.pins.extend(best.pins);
+        }
+    }
+
     Ok(symbol)
 }
 
-// New function to parse the nested symbol section which contains pins in new format
-fn parse_symbol_section(symbol: &mut KicadSymbol, section_data: &[Sexpr]) {
+struct NestedStylePins {
+    style: u32,
+    named_pin_count: usize,
+    pins: Vec<KicadPin>,
+}
+
+fn is_named_pin(pin: &KicadPin) -> bool {
+    !pin.name.is_empty() && pin.name != "~"
+}
+
+// Parse pins from a nested symbol section.
+fn parse_symbol_section(section_data: &[Sexpr]) -> Vec<KicadPin> {
+    let mut pins = Vec::new();
     for item in section_data {
         if let SexprKind::List(pin_data) = &item.kind {
             if let Some(SexprKind::Symbol(type_name)) = pin_data.first().map(|s| &s.kind) {
                 if type_name == "pin" {
                     if let Some(pin) = parse_pin_from_section(pin_data) {
-                        symbol.pins.push(pin);
+                        pins.push(pin);
                     }
                 }
             }
         }
     }
+    pins
+}
+
+fn nested_symbol_unit_style(section_data: &[Sexpr]) -> (u32, u32) {
+    section_data
+        .get(1)
+        .and_then(|n| n.as_str().or_else(|| n.as_sym()))
+        .map(|name| {
+            // Parse trailing `_<unit>_<style>` without constraining the base name.
+            let mut parts = name.rsplitn(3, '_');
+            let style = parts
+                .next()
+                .and_then(|s| s.parse().ok())
+                .unwrap_or_default();
+            let unit = parts
+                .next()
+                .and_then(|s| s.parse().ok())
+                .unwrap_or_default();
+            (unit, style)
+        })
+        .unwrap_or((0, 0))
 }
 
 fn parse_pin_common(pin_data: &[Sexpr]) -> KicadPin {

crates/pcb-eda/tests/test_eda.rs

@@ -178,6 +178,126 @@ fn test_nested_unnamed_pin_preserved_and_uses_number_as_signal_name() {
     assert_eq!(pin_map.get("2"), Some(&"2".to_string()));
 }
 
+#[test]
+fn test_style_1_pin_names_preferred_over_alternate_style() {
+    let content = r#"(kicad_symbol_lib
+  (version 20211014)
+  (generator "test")
+  (symbol "Demo:Diode"
+    (symbol "Diode_1_1"
+      (pin unspecified line
+        (at 0 0 0)
+        (length 2.54)
+        (name "K")
+        (number "1")
+      )
+      (pin unspecified line
+        (at 10.16 0 180)
+        (length 2.54)
+        (name "A")
+        (number "2")
+      )
+    )
+    (symbol "Diode_1_2"
+      (pin unspecified line
+        (at 0 10.16 270)
+        (length 2.54)
+        (name "")
+        (number "1")
+      )
+      (pin unspecified line
+        (at 0 -10.16 90)
+        (length 2.54)
+        (name "")
+        (number "2")
+      )
+    )
+  )
+)"#;
+
+    let lib = SymbolLibrary::from_string(content, "kicad_sym").unwrap();
+    let symbol = lib.first_symbol().unwrap();
+    assert_eq!(symbol.pins.len(), 2);
+
+    let pin_map: HashMap<_, _> = symbol
+        .pins
+        .iter()
+        .map(|pin| (pin.number.clone(), pin.signal_name().to_string()))
+        .collect();
+
+    assert_eq!(pin_map.get("1"), Some(&"K".to_string()));
+    assert_eq!(pin_map.get("2"), Some(&"A".to_string()));
+}
+
+#[test]
+fn test_style_0_only_symbol_is_supported() {
+    let content = r#"(kicad_symbol_lib
+  (version 20211014)
+  (generator "test")
+  (symbol "Demo:Header"
+    (symbol "Header_1_0"
+      (pin passive line
+        (at 0 0 0)
+        (length 2.54)
+        (name "P1")
+        (number "1")
+      )
+      (pin passive line
+        (at 0 -2.54 0)
+        (length 2.54)
+        (name "P2")
+        (number "2")
+      )
+    )
+  )
+)"#;
+
+    let lib = SymbolLibrary::from_string(content, "kicad_sym").unwrap();
+    let symbol = lib.first_symbol().unwrap();
+    assert_eq!(symbol.pins.len(), 2);
+
+    let pin_map: HashMap<_, _> = symbol
+        .pins
+        .iter()
+        .map(|pin| (pin.number.clone(), pin.signal_name().to_string()))
+        .collect();
+
+    assert_eq!(pin_map.get("1"), Some(&"P1".to_string()));
+    assert_eq!(pin_map.get("2"), Some(&"P2".to_string()));
+}
+
+#[test]
+fn test_style_tie_uses_lowest_style_number() {
+    let content = r#"(kicad_symbol_lib
+  (version 20211014)
+  (generator "test")
+  (symbol "Demo:Tie"
+    (symbol "Tie_1_0"
+      (pin passive line
+        (at 0 0 0)
+        (length 2.54)
+        (name "A0")
+        (number "1")
+      )
+    )
+    (symbol "Tie_1_1"
+      (pin passive line
+        (at 0 0 0)
+        (length 2.54)
+        (name "A1")
+        (number "1")
+      )
+    )
+  )
+)"#;
+
+    let lib = SymbolLibrary::from_string(content, "kicad_sym").unwrap();
+    let symbol = lib.first_symbol().unwrap();
+    assert_eq!(symbol.pins.len(), 1);
+    assert_eq!(symbol.pins[0].number, "1");
+    assert_eq!(symbol.pins[0].signal_name(), "A0");
+}
+
 #[test]
 fn test_pcm2903cdb_manufacturer() {
     test_symbol_option_property(