Copilot instructions

1# IQKeyboardManager
2 
3IQKeyboardManager is an iOS library available in both Objective-C and Swift versions that provides automatic keyboard management functionality. The library includes comprehensive demo applications and supports CocoaPods, Carthage, and Swift Package Manager.
4 
5Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
6 
7## Working Effectively
8 
9### Environment Requirements
10- **CRITICAL**: This is an iOS-specific library that requires macOS with Xcode for full development
11- Minimum Xcode 15 for Demo projects
12- Minimum Xcode 13 for library development  
13- iOS 13.0+ target for both Objective-C and Swift versions
14- Swift 5.7+ supported
15 
16### Dependency Management and Setup
17**ALWAYS** perform these steps in order for fresh repository setup:
18 
191. **Install CocoaPods** (on macOS only):
20```bash
21   gem install cocoapods --user-install
22   export PATH=$HOME/.local/share/gem/ruby/3.2.0/bin:$PATH
23```
24 
252. **Install dependencies** (macOS only - NEVER CANCEL - takes 5-10 minutes):
26```bash
27   cd /path/to/IQKeyboardManager
28   pod install --repo-update
29```
30   Set timeout to 15+ minutes. This downloads all dependencies including SwiftLint.
31   **NOTE**: `pod install` fails in sandboxed environments due to network restrictions.
32 
333. **Verify Swift Package Manager dependencies** (works on both macOS and Linux - takes ~2 seconds):
34```bash
35   swift package resolve
36```
37   This resolves all SPM dependencies successfully even on Linux.
38 
394. **Show dependency tree**:
40```bash
41   swift package show-dependencies
42```
43 
44### Build and Test
45**IMPORTANT**: Full builds require macOS with Xcode installed. Linux environments can only validate Swift Package Manager dependency resolution.
46 
47#### On macOS with Xcode:
481. **Build Demo Applications** (NEVER CANCEL - takes 10-15 minutes):
49```bash
50   cd /path/to/IQKeyboardManager
51   xcodebuild -workspace Demo.xcworkspace -scheme DemoSwift -sdk iphonesimulator clean build
52   xcodebuild -workspace Demo.xcworkspace -scheme DemoObjC -sdk iphonesimulator clean build
53```
54   Set timeout to 30+ minutes for each command.
55 
562. **Run UI Tests** (NEVER CANCEL - takes 15-20 minutes):
57```bash
58   xcodebuild -workspace Demo.xcworkspace -scheme DemoObjC -sdk iphonesimulator -destination 'platform=iOS Simulator,name=iPhone 15,OS=17.0' test
59```
60   Set timeout to 45+ minutes.
61 
62#### On Linux (Limited Validation):
63- **Dependency resolution works**: `swift package resolve` (takes ~2 seconds)
64- **Dependency analysis works**: `swift package show-dependencies`
65- **Building FAILS**: `swift build` fails with "no such module 'UIKit'" error (expected)
66- **Cannot run simulators or UI tests** 
67- **CocoaPods may fail** due to network restrictions in sandboxed environments
68 
69### Linting and Code Quality
701. **SwiftLint** (macOS only - installed via CocoaPods):
71```bash
72   Pods/SwiftLint/swiftlint
73```
74   **NOTE**: Not available on Linux or when CocoaPods installation fails.
75   
762. **Check formatting** before commits (macOS only):
77```bash
78   Pods/SwiftLint/swiftlint --fix
79```
80 
813. **Manual code review** (any platform):
82   - Review Swift files in `IQKeyboardManagerSwift/`
83   - Check Objective-C files in `IQKeyboardManager/`
84   - Verify integration examples in demo apps
85 
86## Validation
87 
88### Required Manual Testing Scenarios
89**ALWAYS** test these scenarios after making changes to keyboard management:
90 
911. **Basic Keyboard Management**:
92   - Run DemoSwift app in iOS Simulator  
93   - Navigate to "UITextField/UITextView example"
94   - Tap text fields - verify keyboard shows/hides smoothly
95   - Verify toolbar appears above keyboard with Previous/Next/Done buttons
96   - Test scrolling behavior when keyboard appears
97   - **Validate**: No text fields are obscured by keyboard
98 
992. **Multi-Field Navigation**:
100   - Use Previous/Next buttons in toolbar to navigate between text fields
101   - Verify focus moves correctly between fields
102   - Test with different keyboard types (number pad, email, etc.)
103   - **Validate**: All fields are accessible via keyboard navigation
104 
1053. **Configuration Testing**:
106   - Open Settings in demo app  
107   - Toggle "Enable IQKeyboardManager" - verify keyboard behavior changes
108   - Test different toolbar management options
109   - Verify appearance customization works
110   - **Validate**: Settings changes take effect immediately
111 
1124. **Both Platform Testing**:
113   - Test identical scenarios in both DemoSwift and DemoObjC apps
114   - Ensure Objective-C and Swift versions behave identically
115   - **Validate**: Feature parity between both implementations
116 
1175. **Edge Cases**:
118   - Test with collection views and table views containing text fields
119   - Test with modal presentations and popovers
120   - Test device rotation during text input
121   - **Validate**: Keyboard management works in complex UI scenarios
122 
123### CI Validation
124The project uses Travis CI (`.travis.yml`) with these validation steps:
125```bash
126xcodebuild -workspace Demo.xcworkspace -scheme DemoObjC -sdk iphonesimulator
127xcodebuild -workspace Demo.xcworkspace -scheme DemoSwift -sdk iphonesimulator
128```
129 
130**Always** run these commands locally before committing changes.
131 
132## Key Project Structure
133 
134### Library Files
135- `IQKeyboardManager/` - Objective-C version (legacy)
136- `IQKeyboardManagerSwift/` - Swift version (current)
137  - `IQKeyboardManager/` - Core keyboard management
138  - `Appearance/` - UI appearance customization
139  - `Resign/` - Keyboard dismissal handling
140  - `IQKeyboardToolbarManager/` - Toolbar management
141 
142### Demo Applications  
143- `Demo/Swift_Demo/` - Swift demonstration app (45 Swift files)
144- `Demo/Objective_C_Demo/` - Objective-C demonstration app (28 Objective-C files)
145- `DemoObjCUITests/` - UI test suite
146 
147### Dependencies (Swift Package Manager)
148The Swift version depends on separate modular libraries:
149- IQKeyboardNotification (1.0.5+)
150- IQTextInputViewNotification (1.0.8+) 
151- IQKeyboardToolbarManager (1.1.3+)
152- IQKeyboardReturnManager (1.0.5+)
153- IQTextView (1.0.5+)
154 
155## Platform-Specific Instructions
156 
157### macOS Development
158- Use Xcode 15+ for demo projects
159- Open `Demo.xcworkspace` (NOT `Demo.xcodeproj`)
160- Build times: 10-15 minutes for clean builds
161- UI test runs: 15-20 minutes
162 
163### Linux Development (Limited)
164- Can validate Swift Package Manager dependencies only
165- Cannot build iOS targets or run simulators
166- Use for dependency analysis and non-iOS-specific code review only
167 
168## Validated Commands and Timing
169 
170### Commands That Work on Any Platform
171```bash
172# Fast dependency resolution (~2 seconds)
173swift package resolve
174 
175# Show dependency tree (~1 second)
176swift package show-dependencies
177 
178# Basic file exploration and structure analysis
179find . -name "*.swift" | wc -l  # Count Swift files
180find . -name "*.m" | wc -l      # Count Objective-C files
181```
182 
183### Commands That Work Only on macOS
184```bash
185# CocoaPods installation (5-10 minutes)
186pod install --repo-update
187 
188# Xcode builds (10-15 minutes each)
189xcodebuild -workspace Demo.xcworkspace -scheme DemoSwift -sdk iphonesimulator clean build
190xcodebuild -workspace Demo.xcworkspace -scheme DemoObjC -sdk iphonesimulator clean build
191 
192# UI Tests (15-20 minutes)
193xcodebuild -workspace Demo.xcworkspace -scheme DemoObjC -sdk iphonesimulator test
194```
195 
196### Commands That Fail on Linux (Expected)
197```bash
198# Fails with "no such module 'UIKit'" error
199swift build
200 
201# May fail due to network restrictions
202pod install --repo-update
203```
204 
205## Common Tasks
206 
207### Repository Structure Overview
208```
209IQKeyboardManager/
210├── README.md (236 lines) - Main documentation
211├── CONTRIBUTING.md (52 lines) - Contribution guidelines  
212├── Package.swift - Swift Package Manager configuration
213├── Podfile - CocoaPods configuration for demo apps
214├── Demo.xcworkspace - Xcode workspace (use this, not .xcodeproj)
215├── IQKeyboardManager/ - Objective-C version (legacy)
216├── IQKeyboardManagerSwift/ - Swift version (current)
217│   ├── IQKeyboardManager/ - Core keyboard management (~40KB main file)
218│   │   ├── Configuration/ - Runtime configuration classes
219│   │   ├── Debug/ - Debug utilities
220│   │   ├── Deprecated/ - Backward compatibility  
221│   │   ├── IQKeyboardManagerExtension/ - UIKit extensions
222│   │   └── UIKitExtensions/ - Additional UIKit helpers
223│   ├── Appearance/ - UI appearance customization
224│   ├── Resign/ - Keyboard dismissal handling
225│   └── IQKeyboardToolbarManager/ - Toolbar management
226├── Demo/
227│   ├── Swift_Demo/ - Swift demonstration app (45 Swift files)
228│   │   ├── AppDelegate.swift - Shows basic integration
229│   │   └── ViewController/ - Various usage examples
230│   └── Objective_C_Demo/ - Objective-C demonstration app (28 .m files)
231├── DemoObjCUITests/ - UI test suite
232└── Documentation/ - Migration guides for major versions
233```
234 
235### Key Files to Check After Changes
236- `IQKeyboardManagerSwift/IQKeyboardManager/IQKeyboardManager.swift` - Main library class
237- `Demo/Swift_Demo/AppDelegate.swift` - Basic integration example
238- `Demo/Objective_C_Demo/AppDelegate.m` - Objective-C integration example  
239- Any files in `IQKeyboardManagerSwift/IQKeyboardManagerExtension/` when modifying UIKit behavior
240 
241### Basic Usage Integration
242**Swift**:
243```swift
244import IQKeyboardManagerSwift
245 
246// In AppDelegate.swift
247IQKeyboardManager.shared.isEnabled = true
248IQKeyboardManager.shared.enableAutoToolbar = true
249```
250 
251**Objective-C**:
252```objc
253#import <IQKeyboardManager/IQKeyboardManager.h>
254 
255// In AppDelegate.m
256[[IQKeyboardManager sharedManager] setEnable:YES];
257```
258 
259### Installation Methods
2601. **CocoaPods**: `pod 'IQKeyboardManagerSwift'` or `pod 'IQKeyboardManager'`
2612. **Swift Package Manager**: `https://github.com/hackiftekhar/IQKeyboardManager.git`
2623. **Carthage**: `github "hackiftekhar/IQKeyboardManager"`
263 
264### Documentation Locations
265- `Documentation/` - Migration guides for major versions
266- `README.md` - Installation and basic usage
267- `CONTRIBUTING.md` - Development guidelines
268- Demo apps serve as comprehensive usage examples
269 
270## Troubleshooting
271 
272### Common Issues and Solutions
273 
274**"No such module 'UIKit'" error:**
275- Expected on Linux - this is an iOS-only library
276- Build and test only on macOS with Xcode
277 
278**CocoaPods installation fails:**
279- Check internet connectivity and firewall restrictions
280- Try `pod install --verbose` for detailed error messages  
281- In sandboxed environments, network access may be limited
282 
283**Xcode build fails:**
284- Ensure you're opening `Demo.xcworkspace`, not `Demo.xcodeproj`
285- Clean build folder: `cmd+shift+k` in Xcode
286- Reset simulators if needed
287 
288**UI tests fail:**
289- Ensure iOS Simulator is available and running
290- Check that test devices match requirements (iOS 13.0+)
291- Verify simulator has sufficient disk space
292 
293## CRITICAL: Timeout and Cancellation Guidelines
294 
295### NEVER CANCEL These Commands
296Set appropriate timeouts and wait for completion:
297 
298**Swift Package Manager (works on any platform):**
299- `swift package resolve` - Takes ~2 seconds, set 60 second timeout
300- `swift package show-dependencies` - Takes ~1 second, set 30 second timeout
301 
302**CocoaPods (macOS only):**  
303- `pod install --repo-update` - Takes 5-10 minutes, set 15+ minute timeout
304- NEVER CANCEL during "Installing" or "Generating Pods project" phases
305 
306**Xcode Builds (macOS only):**
307- Clean builds: 10-15 minutes, set 30+ minute timeout
308- Incremental builds: 2-5 minutes, set 15+ minute timeout
309- UI test runs: 15-20 minutes, set 45+ minute timeout
310 
311**Expected Command Failures:**
312- `swift build` on Linux - WILL FAIL with UIKit error (this is correct)
313- `pod install` in restricted networks - MAY FAIL due to network access
314 
315### Build Command Examples with Timeouts
316```bash
317# Swift Package Manager (any platform)
318timeout 60 swift package resolve
319 
320# CocoaPods (macOS only)  
321timeout 900 pod install --repo-update  # 15 minutes
322 
323# Xcode builds (macOS only)
324timeout 1800 xcodebuild -workspace Demo.xcworkspace -scheme DemoSwift -sdk iphonesimulator clean build  # 30 minutes
325timeout 2700 xcodebuild -workspace Demo.xcworkspace -scheme DemoObjC -sdk iphonesimulator test  # 45 minutes
326```