Fix: Tab-Navigation und Arrow-Key-Wrap in NavigationSplitView

- Tab navigates within the active section first; only switches to the
  next section when the current element is the last in its section
- Arrow keys (Up/Down) no longer wrap at section boundaries
- moveFocusInSection gains a wrap: Bool parameter and returns Bool
- Add tests: tabNavigatesWithinSectionFirst, arrowKeysDoNotWrapAtBoundary

Author: phranck

Sources/TUIkit/Focus/Focus.swift

@@ -213,36 +213,46 @@ public extension FocusManager {
     }
 
     /// Moves focus to the next element within the active section.
+    ///
+    /// Arrow-key navigation: does **not** wrap at the boundary.
     func focusNextInSection() {
-        moveFocusInSection(direction: .forward)
+        moveFocusInSection(direction: .forward, wrap: false)
     }
 
     /// Moves focus to the previous element within the active section.
+    ///
+    /// Arrow-key navigation: does **not** wrap at the boundary.
     func focusPreviousInSection() {
-        moveFocusInSection(direction: .backward)
+        moveFocusInSection(direction: .backward, wrap: false)
     }
 
     /// Moves focus to the next focusable element.
     ///
-    /// When multiple sections exist, this cycles between sections.
-    /// When only one section exists, this cycles within it.
+    /// When multiple sections exist, Tab navigates within the current section
+    /// first. Only when the current element is the last in its section does
+    /// Tab switch to the next section.
+    /// When only one section exists, this cycles within it (wrapping).
     func focusNext() {
         if sections.count > 1 {
-            activateNextSection()
+            let moved = moveFocusInSection(direction: .forward, wrap: false)
+            if !moved { activateNextSection() }
         } else {
-            moveFocusInSection(direction: .forward)
+            moveFocusInSection(direction: .forward, wrap: true)
         }
     }
 
     /// Moves focus to the previous focusable element.
     ///
-    /// When multiple sections exist, this cycles between sections.
-    /// When only one section exists, this cycles within it.
+    /// When multiple sections exist, Shift+Tab navigates within the current
+    /// section first. Only when the current element is the first in its section
+    /// does Shift+Tab switch to the previous section.
+    /// When only one section exists, this cycles within it (wrapping).
     func focusPrevious() {
         if sections.count > 1 {
-            activatePreviousSection()
+            let moved = moveFocusInSection(direction: .backward, wrap: false)
+            if !moved { activatePreviousSection() }
         } else {
-            moveFocusInSection(direction: .backward)
+            moveFocusInSection(direction: .backward, wrap: true)
         }
     }
 
@@ -463,26 +473,47 @@ private extension FocusManager {
     }
 
     /// Moves focus within the active section.
-    func moveFocusInSection(direction: FocusDirection) {
-        guard let section = activeSection else { return }
+    ///
+    /// - Parameters:
+    ///   - direction: The direction in which to move focus.
+    ///   - wrap: When `true`, focus wraps around from the last element to the
+    ///     first (and vice versa). When `false`, focus stops at the boundary
+    ///     and the method returns `false`.
+    /// - Returns: `true` if focus moved to a new element, `false` if the
+    ///   boundary was reached (and `wrap` is `false`) or no element is available.
+    @discardableResult
+    func moveFocusInSection(direction: FocusDirection, wrap: Bool = true) -> Bool {
+        guard let section = activeSection else { return false }
 
         let available = section.focusables.filter { $0.canBeFocused }
-        guard !available.isEmpty else { return }
+        guard !available.isEmpty else { return false }
 
         if let currentID = focusedID,
             let currentIndex = available.firstIndex(where: { $0.focusID == currentID })
         {
             let targetIndex: Int
             switch direction {
             case .forward:
-                targetIndex = (currentIndex + 1) % available.count
+                if currentIndex == available.count - 1 {
+                    guard wrap else { return false }
+                    targetIndex = 0
+                } else {
+                    targetIndex = currentIndex + 1
+                }
             case .backward:
-                targetIndex = currentIndex == 0 ? available.count - 1 : currentIndex - 1
+                if currentIndex == 0 {
+                    guard wrap else { return false }
+                    targetIndex = available.count - 1
+                } else {
+                    targetIndex = currentIndex - 1
+                }
             }
             focus(available[targetIndex])
+            return true
         } else {
             let fallbackIndex = direction == .forward ? 0 : available.count - 1
             focus(available[fallbackIndex])
+            return true
         }
     }
 

Tests/TUIkitTests/FocusSectionTests.swift

@@ -196,6 +196,75 @@ struct FocusSectionTests {
         #expect(manager.isFocused(pageBtn))
     }
 
+    @Test("Tab navigates within section before switching to next section")
+    func tabNavigatesWithinSectionFirst() {
+        let manager = FocusManager()
+
+        manager.registerSection(id: "sidebar")
+        manager.registerSection(id: "detail")
+
+        let sidebarBtn = MockFocusable(id: "sidebar-btn")
+        let detailBtn1 = MockFocusable(id: "detail-btn-1")
+        let detailBtn2 = MockFocusable(id: "detail-btn-2")
+
+        manager.register(sidebarBtn, inSection: "sidebar")
+        manager.register(detailBtn1, inSection: "detail")
+        manager.register(detailBtn2, inSection: "detail")
+
+        // Switch to detail section with two elements
+        manager.activateSection(id: "detail")
+        #expect(manager.isActiveSection("detail"))
+        #expect(manager.isFocused(detailBtn1))
+
+        let tabEvent = KeyEvent(key: .tab, ctrl: false, alt: false, shift: false)
+
+        // Tab → stays in detail, focuses second element
+        manager.dispatchKeyEvent(tabEvent)
+        #expect(manager.isActiveSection("detail"), "Tab should stay in detail when not at last element")
+        #expect(manager.isFocused(detailBtn2))
+
+        // Tab again → now at last element, switches to next section (sidebar)
+        manager.dispatchKeyEvent(tabEvent)
+        #expect(manager.isActiveSection("sidebar"), "Tab at last element should switch to next section")
+        #expect(manager.isFocused(sidebarBtn))
+    }
+
+    @Test("Arrow keys do not wrap at section boundary")
+    func arrowKeysDoNotWrapAtBoundary() {
+        let manager = FocusManager()
+
+        manager.registerSection(id: "panel")
+
+        let item1 = MockFocusable(id: "item-1")
+        let item2 = MockFocusable(id: "item-2")
+        let item3 = MockFocusable(id: "item-3")
+
+        manager.register(item1, inSection: "panel")
+        manager.register(item2, inSection: "panel")
+        manager.register(item3, inSection: "panel")
+
+        // Navigate to last element
+        #expect(manager.isFocused(item1))
+        let downEvent = KeyEvent(key: .down, ctrl: false, alt: false, shift: false)
+        manager.dispatchKeyEvent(downEvent)
+        manager.dispatchKeyEvent(downEvent)
+        #expect(manager.isFocused(item3))
+
+        // Down at last element: stays at item3 (no wrap)
+        manager.dispatchKeyEvent(downEvent)
+        #expect(manager.isFocused(item3), "Down arrow at last element should not wrap")
+
+        // Navigate to first element
+        let upEvent = KeyEvent(key: .up, ctrl: false, alt: false, shift: false)
+        manager.dispatchKeyEvent(upEvent)
+        manager.dispatchKeyEvent(upEvent)
+        #expect(manager.isFocused(item1))
+
+        // Up at first element: stays at item1 (no wrap)
+        manager.dispatchKeyEvent(upEvent)
+        #expect(manager.isFocused(item1), "Up arrow at first element should not wrap")
+    }
+
     @Test("Single section: Tab cycles elements within it")
     func singleSectionTabCyclesElements() {
         let manager = FocusManager()