[iOS] Add Support for List Item Focus Area #602

kavanbrandon · 2025-10-01T16:06:52Z

Describe your changes here. Please include screenshots if they're visual!

This PR adds support for keyboard focus navigation on iOS, enabling users to navigate list items using keyboard input (Tab, Arrow keys, Return/Space) for improved accessibility and external keyboard support.

Key Changes

1. New Focus Configuration API

Added Behavior.FocusConfiguration enum with three modes:

.none - No focus support (default)
.allowsFocus - Basic keyboard navigation with always-visible focus ring
.selectionFollowsFocus(showFocusRing: Bool) - Navigation where selection follows focus

3. Demo Integration

Added KeyboardNavigationDemoViewController showcasing:

Focus navigation between items
Toggle controls for different focus modes
Mixed selection styles (selectable, tappable, toggles, non-selectable)
Instructions for keyboard usage

Usage Example

// Basic focus navigation with always-visible ring
list.behavior.focus = .allowsFocus

// Focus navigation where selection follows focus
list.behavior.focus = .selectionFollowsFocus(showFocusRing: true)

// Disable focus navigation
list.behavior.focus = .none // or nil

Demo Videos

Demo 1: Selection Follows Focus:
Demo 2: Allows Focus (pressing enter triggers a selection)

Screen.Recording.2025-10-20.at.11.01.09.AM.mov

Screen.Recording.2025-10-20.at.11.04.38.AM.mov

Checklist

Please do the following before merging:

Ensure any public-facing changes are reflected in the changelog. Include them in the Main section.

soroushsq · 2025-10-23T17:23:50Z

ListableUI/Sources/Behavior.swift

+            }
+        }
+
+        public static func == (lhs: FocusConfiguration, rhs: FocusConfiguration) -> Bool {


Can this implementation be automatically synthesized?

Yep, I removed this!

soroushsq · 2025-10-23T17:24:25Z

ListableUI/Sources/ListView/ListView.swift

+        switch self.behavior.focus {
+        case nil, .some(.none):


Does this .some(.none) mean that there is a double optional thing going on here?

Updated so the .some(.none) case is no longer relevant.

johnnewman-square

This is looking great, including the demo. Thanks for making these updates. I left just a few notes that I'd like to iron out.

johnnewman-square · 2025-10-27T13:57:47Z

ListableUI/Sources/Behavior.swift

+
+    /// Configuration for keyboard focus behavior in the list view.
+    ///
+    /// - `nil`: No focus support - keyboard navigation is disabled
+    /// - `.none`: Explicitly disabled focus support
+    /// - `.allowsFocus`: Basic focus support with keyboard navigation, but selection doesn't follow focus
+    /// - `.selectionFollowsFocus`: Focus support where selection automatically follows focus changes
+    ///
+    /// When focus is enabled, items that support selection can receive focus for keyboard navigation.
+    /// The focus ring will be applied to focused items automatically.
+    public var focus: FocusConfiguration?


If nil and none are identical in behavior, it could be a nice change to consolidate them into none and make focus a non-optional variable. I think that would simplify the overall mental model of these two variants and could remove the need for the nil guards in ListView.Delegate.

This is similar to how PageScrollingBehavior was built, where the Behavior's pageScrollingBehavior init parameter defaults to none instead of nil. Curious on your thoughts!

Great suggestion! I went ahead and made this change. The focus property is now non-optional and defaults to .none. Also removed all the optional guards in the delegate methods and simplified switch statements.

johnnewman-square · 2025-10-27T14:20:26Z

Development/Sources/Demos/Demo Screens/KeyboardNavigationDemoViewController.swift

+                Item(
+                    DemoItem(text: "Toggle Item (Focus + Toggle)"),
+                    selectionStyle: .toggles(),
+                    onSelect: { _ in
+                        print("Toggled Toggle Item")
+                    }
+                )


I noticed that after toggling this item, the focus selection is reset the next time I use the arrow keys for navigation. If we wanted the focused item to be preserved, is this behavior that needs to be configured by the client, or could that be something internal to our UICollectionView implementation within Listable?

(I did not have full keyboard access enabled during this flow.)

ScreenRecording_10-27-2025.10-16-24_1.mov

This is interesting! It's hard to tell from the documentation but I wonder if this is expected UIKit behavior. When the toggle item deselects, UICollectionView loses the current focus anchor and re-evaluates from the beginning of the focus group. I think one potential solution is leveraging focusgroupidentifier and focusgrouppriority and updating a cell's focusgrouppriority if it's deselected.

Curious if you're ok with keeping the current changes for now and we could add focus preservation logic for toggles in a follow-up? I can create a ticket to track it.

Got it! Increasing the priority when deselected sounds like a good idea to try out. Interestingly, when using full keyboard access, the toggled item stays focused between toggle states (video below). So this issue seems to be isolated to standard focus and will impact a smaller subset of users. I'm on board with merging if you'd like to move toggle focus preservation to a followup ticket!

ScreenRecording_10-31-2025.14-11-25_1.mov

I've made a ticket here: https://block.atlassian.net/browse/UI-9566

@johnnewman-square Would you be able to merge on your end? I don't have the option to do so.

Sure thing! I'll kick off one more set of test actions and merge.

johnnewman-square · 2025-10-27T14:25:38Z

Development/Sources/Demos/Demo Screens/KeyboardNavigationDemoViewController.swift

+        list.add {
+            Section("instructions") {
+                Item(
+                    DemoItem(text: "Instructions:\n• Use Arrow keys to navigate within the list\n• Press Return/Space to select items\n• Toggle settings with navigation buttons"),


In my testing flows, the space key will only function as return when full keyboard access is enabled. If that's right, could we add that detail to the demo text? Thanks!

That's correct. I've added updated demo text.

johnnewman-square · 2025-10-27T14:31:09Z

Package.resolved

With the Tuist setup storing Package.resolved under Development/Tuist/, we should be able to remove this file.

johnnewman-square

These changes look good. Thank you for addressing the feedback!

soroushsq

Just a quick code golfy thing

soroushsq · 2025-11-03T14:51:23Z

ListableUI/Sources/ListView/ListView.Delegate.swift

+            if view.behavior.focus.allowsFocus {
+                cell.focusEffect = view.behavior.focus.showFocusRing ? UIFocusHaloEffect() : nil
+            } else {
+                cell.focusEffect = nil
+            }


Suggested change

if view.behavior.focus.allowsFocus {

cell.focusEffect = view.behavior.focus.showFocusRing ? UIFocusHaloEffect() : nil

} else {

cell.focusEffect = nil

}

cell.focusEffect = view.behavior.focus.allowsFocus && view.behavior.focus.showFocusRing ? UIFocusHaloEffect() : nil

@soroushsq Updated!

kavanbrandon force-pushed the kavan/feat-ios-add-focus-area-support-for-list-items branch 11 times, most recently from 8c87d32 to c9f8575 Compare October 18, 2025 15:27

soroushsq reviewed Oct 23, 2025

View reviewed changes

kavanbrandon force-pushed the kavan/feat-ios-add-focus-area-support-for-list-items branch 7 times, most recently from a0fc0a2 to dfa161f Compare October 23, 2025 23:45

kavanbrandon marked this pull request as ready for review October 23, 2025 23:47

johnnewman-square reviewed Oct 27, 2025

View reviewed changes

kavanbrandon force-pushed the kavan/feat-ios-add-focus-area-support-for-list-items branch 2 times, most recently from 5ad8b50 to b84698c Compare October 30, 2025 19:48

johnnewman-square approved these changes Oct 31, 2025

View reviewed changes

soroushsq approved these changes Nov 3, 2025

View reviewed changes

[iOS] Add Support for List Item Focus Area

612e1c8

kavanbrandon force-pushed the kavan/feat-ios-add-focus-area-support-for-list-items branch from b84698c to 612e1c8 Compare November 3, 2025 23:12

johnnewman-square merged commit 5cf93fa into square:main Nov 4, 2025
3 checks passed

[iOS] Add Support for List Item Focus Area #602

[iOS] Add Support for List Item Focus Area #602

Uh oh!

Conversation

kavanbrandon commented Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Describe your changes here. Please include screenshots if they're visual!

Key Changes

1. New Focus Configuration API

3. Demo Integration

Usage Example

Demo Videos

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

johnnewman-square left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

johnnewman-square left a comment

Choose a reason for hiding this comment

Uh oh!

soroushsq left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kavanbrandon commented Oct 1, 2025 •

edited

Loading