chore: sync upstream PR #7599 - fix(ios): allow enabling gesture navigation via config (#3808)

[riderx]

Upstream PR Sync

This PR syncs changes from an external contributor's PR on the official Capacitor repository.

Original PR

• PR: #7599
• Title: fix(ios): allow enabling gesture navigation via config (feat: Add Back/Forward navigation gestures to ios app ionic-team/capacitor#3808)
• Author: @MegaMaddin

Automation

• CI will run automatically
• Claude Code will review for security/breaking changes
• If approved, this PR will be auto-merged

---

Synced from upstream by Capacitor+ Bot

Summary by CodeRabbit

• New Features
  • Added iOS configuration option to enable or disable back/forward swipe gesture navigation.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

This PR adds support for a new allowsBackForwardNavigationGestures configuration option across the iOS Capacitor implementation. The feature enables users to control whether WKWebView permits back/forward navigation swipe gestures through configuration files, threading the setting from CAPInstanceDescriptor through CAPInstanceConfiguration to CAPBridgeViewController.

Changes

Cohort / File(s)	Summary
Configuration Descriptor Definition ios/Capacitor/Capacitor/CAPInstanceDescriptor.h, ios/Capacitor/Capacitor/CAPInstanceDescriptor.m, ios/Capacitor/Capacitor/CAPInstanceDescriptor.swift	Adds new allowsBackForwardNavigationGestures property (BOOL) to CAPInstanceDescriptor with default initialization to NO. Extends Swift configuration parser to read ios.allowsBackForwardNavigationGestures from capacitor config.
Configuration Instance Processing ios/Capacitor/Capacitor/CAPInstanceConfiguration.h, ios/Capacitor/Capacitor/CAPInstanceConfiguration.m	Adds new readonly allowsBackForwardNavigationGestures property to CAPInstanceConfiguration and propagates the value during initialization from both CAPInstanceDescriptor and existing CAPInstanceConfiguration instances.
WebView Configuration Application ios/Capacitor/Capacitor/CAPBridgeViewController.swift	Applies the allowsBackForwardNavigationGestures configuration value to the WKWebView instance during web view preparation.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Verify the property initialization chain flows correctly from CAPInstanceDescriptor → CAPInstanceConfiguration → CAPBridgeViewController → WKWebView
• Confirm consistent property naming and types across ObjC headers, implementations, and Swift files
• Check that default value (NO) is properly set in all initialization paths

Poem

🐰✨ A config hop, a gesture flows,
Back and forward, the swiper goes!
From descriptor down through channels deep,
WKWebView's navigation we shall keep. 🎯

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: syncing an upstream PR that enables iOS gesture navigation via configuration.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch sync/upstream-pr-7599

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d7f7689 and 4354ce2.

📒 Files selected for processing (6)

• ios/Capacitor/Capacitor/CAPBridgeViewController.swift (1 hunks)
• ios/Capacitor/Capacitor/CAPInstanceConfiguration.h (1 hunks)
• ios/Capacitor/Capacitor/CAPInstanceConfiguration.m (2 hunks)
• ios/Capacitor/Capacitor/CAPInstanceDescriptor.h (1 hunks)
• ios/Capacitor/Capacitor/CAPInstanceDescriptor.m (1 hunks)
• ios/Capacitor/Capacitor/CAPInstanceDescriptor.swift (1 hunks)

🧰 Additional context used

🪛 Clang (14.0.6)

ios/Capacitor/Capacitor/CAPInstanceConfiguration.h

[error] 22-22: expected identifier or '('

(clang-diagnostic-error)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: test-android
• GitHub Check: test-ios (/Applications/Xcode_26.0.app)
• GitHub Check: test-cli
• GitHub Check: test-core

🔇 Additional comments (6)

ios/Capacitor/Capacitor/CAPInstanceDescriptor.m (1)

42-42: LGTM! Default initialization is correct.

The default value of NO preserves existing behavior (gestures disabled), preventing any breaking changes. The placement is consistent with surrounding properties.

ios/Capacitor/Capacitor/CAPInstanceDescriptor.swift (1)

114-116: LGTM! Configuration parsing is correctly implemented.

The implementation follows the established pattern for boolean configuration options, with proper optional unwrapping and assignment.

ios/Capacitor/Capacitor/CAPBridgeViewController.swift (1)

304-304: LGTM! WebView configuration is correctly applied.

The configuration value is properly applied to the WKWebView during preparation, following the same pattern as allowsLinkPreview.

ios/Capacitor/Capacitor/CAPInstanceConfiguration.h (1)

22-22: LGTM! Property declaration is correct.

The property declaration follows the correct Objective-C syntax and pattern. The static analysis error is a false positive—the syntax is valid.

ios/Capacitor/Capacitor/CAPInstanceConfiguration.m (2)

34-34: LGTM! Property propagation is correctly implemented.

The value is properly copied from the descriptor during initialization.

---

74-74: LGTM! Configuration copying is correctly implemented.

The value is properly propagated when creating a new configuration instance.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Minor typo in documentation comment.

The property declaration is correct and follows the established pattern. However, there's an extra space before the period on line 97: "gesture navigation ." should be "gesture navigation."

Apply this diff to fix the typo:

 /**
- @brief Whether or not the web view will allow gesture navigation .
+ @brief Whether or not the web view will allow gesture navigation.
  @discussion Set by @c ios.allowsBackForwardNavigationGestures in the configuration file. Corresponds to @c allowsBackForwardNavigationGestures on WKWebView.
  */
 @property (nonatomic, assign) BOOL allowsBackForwardNavigationGestures;

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	/**
	@brief Whether or not the web view will allow gesture navigation .
	@discussion Set by @c ios.allowsBackForwardNavigationGestures in the configuration file. Corresponds to @c allowsBackForwardNavigationGestures on WKWebView.
	*/
	@property (nonatomic, assign) BOOL allowsBackForwardNavigationGestures;
	/**
	@brief Whether or not the web view will allow gesture navigation.
	@discussion Set by @c ios.allowsBackForwardNavigationGestures in the configuration file. Corresponds to @c allowsBackForwardNavigationGestures on WKWebView.
	*/
	@property (nonatomic, assign) BOOL allowsBackForwardNavigationGestures;

🤖 Prompt for AI Agents

In ios/Capacitor/Capacitor/CAPInstanceDescriptor.h around lines 96 to 100, the
documentation comment has an extra space before the period in "gesture
navigation ."; remove the stray space so the sentence reads "gesture
navigation." to match the established comment formatting and punctuation.