Adjust _WKWebExtensionWindow and _WKWebExtensionTab APIs based on fee…

…dback.

https://webkit.org/b/260156

Reviewed by Brian Weinstein.

* Added delegate methods for window and tab creation with new helper classes to hold sugested properties
for the new windows and tabs.
* Have all action methods for windows and tabs take a completionHandler so clients that need do do them
async can report when they are complete.
* Renamed isEphemerial to isUsingPrivateBrowsing to be more clear and match common wording.
* Added missing close method, and setter methods for frame and windowState on the window protocol.
* Removed method for isEphemeral on the tab protocol, since tabs are required to be in a private window.
* Added missing activate, duplicate, and setZoomFactor methods on the tab protocol.

* Source/WebKit/Modules/OSX_Private.modulemap: Added new headers.
* Source/WebKit/Modules/iOS_Private.modulemap: Added new headers.
* Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionContext.mm:
(toImpl): Fix the cases for All and None.
(-[_WKWebExtensionContext didActivateTab:]): Added.
* Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionController.h:
* Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionController.mm:
(-[_WKWebExtensionController didActivateTab:]): Added.
* Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionControllerDelegate.h:
* Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionTab.h:
* Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionTabCreationOptions.h: Added.
* Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionTabCreationOptions.mm: Added.
(-[_WKWebExtensionTabCreationOptions _init]):
* Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionTabCreationOptionsInternal.h: Added.
* Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionWindow.h:
* Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionWindowCreationOptions.h: Added.
* Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionWindowCreationOptions.mm: Added.
(-[_WKWebExtensionWindowCreationOptions _init]):
* Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionWindowCreationOptionsInternal.h: Added.
* Source/WebKit/UIProcess/Extensions/Cocoa/WebExtensionContextCocoa.mm:
(WebKit::WebExtensionContext::didActivateTab): Added.
* Source/WebKit/UIProcess/Extensions/Cocoa/WebExtensionTabCocoa.mm:
(WebKit::WebExtensionTab::WebExtensionTab):
(WebKit::WebExtensionTab::window const):
(WebKit::WebExtensionTab::index const): Added.
(WebKit::WebExtensionTab::isPrivate const): Return the result from the containing window.
(WebKit::WebExtensionTab::toggleReaderMode):
(WebKit::WebExtensionTab::mute):
(WebKit::WebExtensionTab::unmute):
(WebKit::WebExtensionTab::detectWebpageLocale):
(WebKit::WebExtensionTab::loadURL):
(WebKit::WebExtensionTab::reload):
(WebKit::WebExtensionTab::reloadFromOrigin):
(WebKit::WebExtensionTab::goBack):
(WebKit::WebExtensionTab::goForward):
(WebKit::WebExtensionTab::activate): Added.
(WebKit::WebExtensionTab::select):
(WebKit::WebExtensionTab::duplicate):
(WebKit::WebExtensionTab::close):
* Source/WebKit/UIProcess/Extensions/Cocoa/WebExtensionWindowCocoa.mm:
(WebKit::WebExtensionWindow::WebExtensionWindow):
(WebKit::toAPI): Added.
(WebKit::WebExtensionWindow::setState): Added.
(WebKit::WebExtensionWindow::isPrivate const): Renamed from isEphemeral.
(WebKit::WebExtensionWindow::setFrame): Added.
(WebKit::WebExtensionWindow::close): Added.
(WebKit::WebExtensionWindow::isEphemeral const): Deleted.
* Source/WebKit/UIProcess/Extensions/WebExtensionTab.h:
* Source/WebKit/UIProcess/Extensions/WebExtensionWindow.h:
* Source/WebKit/WebKit.xcodeproj/project.pbxproj: Added new files.

Canonical link: https://commits.webkit.org/267240@main

Source/WebKit/Modules/OSX_Private.modulemap

@@ -2184,6 +2184,11 @@ framework module WebKit_Private [system] {
     export *
   }
 
+  explicit module _WKWebExtensionTabCreationOptions {
+    header "_WKWebExtensionTabCreationOptions.h"
+    export *
+  }
+
   explicit module _WKWebExtensionUtilities {
     header "_WKWebExtensionUtilities.h"
     export *
@@ -2199,6 +2204,11 @@ framework module WebKit_Private [system] {
     export *
   }
 
+  explicit module _WKWebExtensionWindowCreationOptions {
+    header "_WKWebExtensionWindowCreationOptions.h"
+    export *
+  }
+
   explicit module _WKWebViewPrintFormatter {
     header "_WKWebViewPrintFormatter.h"
     export *

Source/WebKit/Modules/iOS_Private.modulemap

@@ -3086,6 +3086,11 @@ framework module WebKit_Private [system] {
     export *
   }
 
+  explicit module _WKWebExtensionTabCreationOptions {
+    header "_WKWebExtensionTabCreationOptions.h"
+    export *
+  }
+
   explicit module _WKWebExtensionUtilities {
     header "_WKWebExtensionUtilities.h"
     export *
@@ -3101,6 +3106,11 @@ framework module WebKit_Private [system] {
     export *
   }
 
+  explicit module _WKWebExtensionWindowCreationOptions {
+    header "_WKWebExtensionWindowCreationOptions.h"
+    export *
+  }
+
   explicit module _WKWebViewPrintFormatter {
     header "_WKWebViewPrintFormatter.h"
     export *

Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionContext.h

@@ -493,7 +493,7 @@ WK_CLASS_AVAILABLE(macos(13.3), ios(16.4))
 /*!
  @abstract Should be called by the app when a window is closed to fire appropriate events with only this extension.
  @param newWindow The window that was closed.
- @discussion This method informs only the specific extension of the closure of a window. If the intention is to inform all loaded 
+ @discussion This method informs only the specific extension of the closure of a window. If the intention is to inform all loaded
  extensions consistently, you should use the respective method on the extension controller instead.
  @seealso didOpenWindow:
  @seealso openWindows
@@ -522,13 +522,21 @@ WK_CLASS_AVAILABLE(macos(13.3), ios(16.4))
  @abstract Should be called by the app when a tab is closed to fire appropriate events with only this extension.
  @param closedTab The tab that was closed.
  @param windowIsClosing A boolean value indicating whether the window containing the tab is also closing.
- @discussion This method informs only the specific extension of the closure of a tab. If the intention is to inform all loaded 
+ @discussion This method informs only the specific extension of the closure of a tab. If the intention is to inform all loaded
  extensions consistently, you should use the respective method on the extension controller instead.
  @seealso didOpenTab:
  @seealso openTabs
  */
 - (void)didCloseTab:(id <_WKWebExtensionTab>)closedTab windowIsClosing:(BOOL)windowIsClosing;
 
+/*!
+ @abstract Should be called by the app when a tab is activated to notify only this specific extension.
+ @param activatedTab The activated tab.
+ @discussion This method informs only the specific extension of the tab activation. If the intention is to inform all loaded
+ extensions consistently, you should use the respective method on the extension controller instead.
+ */
+- (void)didActivateTab:(id <_WKWebExtensionTab>)activatedTab;
+
 /*!
  @abstract Should be called by the app when tabs are selected to fire appropriate events with only this extension.
  @param selectedTabs The set of tabs that were selected. An empty set indicates that no tabs are currently selected or that the
@@ -543,7 +551,7 @@ WK_CLASS_AVAILABLE(macos(13.3), ios(16.4))
  @param movedTab The tab that was moved.
  @param index The old index of the tab within the window.
  @param oldWindow The window that the tab was moved from, or \c nil if the window stayed the same.
- @discussion This method informs only the specific extension that a tab has been moved. If the intention is to inform all loaded 
+ @discussion This method informs only the specific extension that a tab has been moved. If the intention is to inform all loaded
  extensions consistently, you should use the respective method on the extension controller instead.
  */
 - (void)didMoveTab:(id <_WKWebExtensionTab>)movedTab fromIndex:(NSUInteger)index inWindow:(nullable id <_WKWebExtensionWindow>)oldWindow NS_SWIFT_NAME(didMoveTab(_:from:in:));
@@ -552,7 +560,7 @@ WK_CLASS_AVAILABLE(macos(13.3), ios(16.4))
  @abstract Should be called by the app when a tab is replaced by another tab to fire appropriate events with only this extension.
  @param oldTab The tab that was replaced.
  @param newTab The tab that replaced the old tab.
- @discussion This method informs only the specific extension that a tab has been replaced. If the intention is to inform all loaded 
+ @discussion This method informs only the specific extension that a tab has been replaced. If the intention is to inform all loaded
  extensions consistently, you should use the respective method on the extension controller instead.
  */
 - (void)didReplaceTab:(id <_WKWebExtensionTab>)oldTab withTab:(id <_WKWebExtensionTab>)newTab NS_SWIFT_NAME(didReplaceTab(_:with:));
@@ -561,7 +569,7 @@ WK_CLASS_AVAILABLE(macos(13.3), ios(16.4))
  @abstract Should be called by the app when the properties of a tab are changed to fire appropriate events with only this extension.
  @param properties The properties of the tab that were changed.
  @param changedTab The tab whose properties were changed.
- @discussion This method informs only the specific extension of the changes to a tab's properties. If the intention is to inform all loaded 
+ @discussion This method informs only the specific extension of the changes to a tab's properties. If the intention is to inform all loaded
  extensions consistently, you should use the respective method on the extension controller instead.
  */
 - (void)didChangeTabProperties:(_WKWebExtensionTabChangedProperties)properties forTab:(id <_WKWebExtensionTab>)changedTab NS_SWIFT_NAME(didChangeTabProperties(_:for:));

Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionContext.mm

@@ -581,6 +581,13 @@ - (void)didCloseTab:(id<_WKWebExtensionTab>)closedTab windowIsClosing:(BOOL)wind
     _webExtensionContext->didCloseTab(toImpl(closedTab, *_webExtensionContext), windowIsClosing ? WebKit::WebExtensionContext::WindowIsClosing::Yes : WebKit::WebExtensionContext::WindowIsClosing::No);
 }
 
+- (void)didActivateTab:(id<_WKWebExtensionTab>)activatedTab
+{
+    NSParameterAssert([activatedTab conformsToProtocol:@protocol(_WKWebExtensionTab)]);
+
+    _webExtensionContext->didActivateTab(toImpl(activatedTab, *_webExtensionContext));
+}
+
 - (void)didSelectTabs:(NSSet<id<_WKWebExtensionTab>> *)selectedTabs
 {
     NSParameterAssert([selectedTabs isKindOfClass:NSSet.class]);
@@ -609,8 +616,13 @@ - (void)didReplaceTab:(id<_WKWebExtensionTab>)oldTab withTab:(id<_WKWebExtension
 {
     OptionSet<WebKit::WebExtensionTab::ChangedProperties> result;
 
-    if (properties & _WKWebExtensionTabChangedPropertiesNone)
-        result.add(WebKit::WebExtensionTab::ChangedProperties::None);
+    if (properties == _WKWebExtensionTabChangedPropertiesNone)
+        return result;
+
+    if (properties == _WKWebExtensionTabChangedPropertiesAll) {
+        result.add(WebKit::WebExtensionTab::ChangedProperties::All);
+        return result;
+    }
 
     if (properties & _WKWebExtensionTabChangedPropertiesAudible)
         result.add(WebKit::WebExtensionTab::ChangedProperties::Audible);
@@ -639,9 +651,6 @@ - (void)didReplaceTab:(id<_WKWebExtensionTab>)oldTab withTab:(id<_WKWebExtension
     if (properties & _WKWebExtensionTabChangedPropertiesZoomFactor)
         result.add(WebKit::WebExtensionTab::ChangedProperties::ZoomFactor);
 
-    if (properties & _WKWebExtensionTabChangedPropertiesAll)
-        result.add(WebKit::WebExtensionTab::ChangedProperties::All);
-
     return result;
 }
 
@@ -922,6 +931,10 @@ - (void)didCloseTab:(id<_WKWebExtensionTab>)closedTab windowIsClosing:(BOOL)wind
 {
 }
 
+- (void)didActivateTab:(id<_WKWebExtensionTab>)activatedTab
+{
+}
+
 - (void)didSelectTabs:(NSSet<id<_WKWebExtensionTab>> *)selectedTabs
 {
 }

Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionController.h

@@ -157,6 +157,14 @@ WK_CLASS_AVAILABLE(macos(13.3), ios(16.4))
  */
 - (void)didCloseTab:(id <_WKWebExtensionTab>)closedTab windowIsClosing:(BOOL)windowIsClosing;
 
+/*!
+ @abstract Should be called by the app when a tab is activated to notify all loaded web extensions.
+ @param activatedTab The activated tab.
+ @discussion This method informs all loaded extensions of the tab activation, ensuring consistent state awareness across extensions.
+ If the intention is to inform only a specific extension, use the respective method on that extension's context instead.
+ */
+- (void)didActivateTab:(id <_WKWebExtensionTab>)activatedTab;
+
 /*!
  @abstract Should be called by the app when tabs are selected to fire appropriate events with all loaded web extensions.
  @param selectedTabs The set of tabs that were selected. An empty set indicates that no tabs are currently selected or that the

Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionController.mm

@@ -164,6 +164,14 @@ - (void)didCloseTab:(id<_WKWebExtensionTab>)closedTab windowIsClosing:(BOOL)wind
         [context->wrapper() didCloseTab:closedTab windowIsClosing:windowIsClosing];
 }
 
+- (void)didActivateTab:(id<_WKWebExtensionTab>)activatedTab
+{
+    NSParameterAssert([activatedTab conformsToProtocol:@protocol(_WKWebExtensionTab)]);
+
+    for (auto& context : _webExtensionController->extensionContexts())
+        [context->wrapper() didActivateTab:activatedTab];
+}
+
 - (void)didSelectTabs:(NSSet<id<_WKWebExtensionTab>> *)selectedTabs
 {
     NSParameterAssert([selectedTabs isKindOfClass:NSSet.class]);
@@ -273,6 +281,10 @@ - (void)didCloseTab:(id<_WKWebExtensionTab>)closedTab windowIsClosing:(BOOL)wind
 {
 }
 
+- (void)didActivateTab:(id<_WKWebExtensionTab>)activatedTab
+{
+}
+
 - (void)didSelectTabs:(NSSet<id<_WKWebExtensionTab>> *)selectedTabs
 {
 }

Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionControllerDelegate.h

@@ -30,8 +30,10 @@
 #import <WebKit/_WKWebExtensionPermission.h>
 
 @class _WKWebExtensionContext;
-@class _WKWebExtensionMatchPattern;
 @class _WKWebExtensionController;
+@class _WKWebExtensionMatchPattern;
+@class _WKWebExtensionTabCreationOptions;
+@class _WKWebExtensionWindowCreationOptions;
 @protocol _WKWebExtensionTab;
 @protocol _WKWebExtensionWindow;
 
@@ -67,6 +69,34 @@ WK_API_AVAILABLE(macos(13.3), ios(16.4))
  */
 - (nullable id <_WKWebExtensionWindow>)webExtensionController:(_WKWebExtensionController *)controller focusedWindowForExtensionContext:(_WKWebExtensionContext *)extensionContext NS_SWIFT_NAME(webExtensionController(_:focusedWindowFor:));
 
+/*!
+ @abstract Called when an extension context requests a new window to be opened.
+ @param controller The web extension controller that is managing the extension.
+ @param options The set of options specifying how the new window should be created.
+ @param extensionContext The context in which the web extension is running.
+ @param completionHandler A block to be called with the newly created window or \c nil if the window wasn't created. An error should be
+ provided if any errors occured.
+ @discussion This method should be implemented by the app to handle requests to open new windows. The app can decide how to handle
+ the creation based on the provided options and existing windows. Once handled, the app should call the completion block with the created window
+ or `nil` if the creation was declined or failed. If not implemented or the completion block is not called within a reasonable amount of time, the
+ request is assumed to have been denied.
+ */
+- (void)webExtensionController:(_WKWebExtensionController *)controller openNewWindowWithOptions:(_WKWebExtensionWindowCreationOptions *)options forExtensionContext:(_WKWebExtensionContext *)extensionContext completionHandler:(void (^)(id <_WKWebExtensionWindow> _Nullable newWindow, NSError * _Nullable error))completionHandler NS_SWIFT_NAME(webExtensionController(_:openNewWindowWithOptions:for:completionHandler:));
+
+/*!
+ @abstract Called when an extension context requests a new tab to be opened.
+ @param controller The web extension controller that is managing the extension.
+ @param options The set of options specifying how the new tab should be created.
+ @param extensionContext The context in which the web extension is running.
+ @param completionHandler A block to be called with the newly created tab or \c nil if the tab wasn't created. An error should be
+ provided if any errors occured.
+ @discussion This method should be implemented by the app to handle requests to open new tabs. The app can decide how to handle
+ the creation based on the provided options and existing tabs. Once handled, the app should call the completion block with the created tab
+ or `nil` if the creation was declined or failed. If not implemented or the completion block is not called within a reasonable amount of time,
+ the request is assumed to have been denied.
+ */
+- (void)webExtensionController:(_WKWebExtensionController *)controller openNewTabWithOptions:(_WKWebExtensionTabCreationOptions *)options forExtensionContext:(_WKWebExtensionContext *)extensionContext completionHandler:(void (^)(id <_WKWebExtensionTab> _Nullable newTab, NSError * _Nullable error))completionHandler NS_SWIFT_NAME(webExtensionController(_:openNewTabWithOptions:for:completionHandler:));
+
 /*!
  @abstract Called when an extension context requests permissions.
  @param controller The web extension controller that is managing the extension.