I have found one use case where NSViewRepresentable breaks completely, stops responding and the worst of all: does not raise any error, exception, nor warning.

The exact same use case works as expected using UIViewRepresentable.

Context

The app

Web is a Browser for iOS and macOS, built on top of SwiftUI to empower a better User Experience, and higher Usability.

Frameworks

SwiftUI is not enough to build a web browser, it has its limitations, the hardest one for being that WebKit is not supported yet, and very likely it will never be, or at least not soon; this is just my uneducated, and potentially inaccurate prediction after having worked with WebKit for several years.

WebKit

Historically, any web browser for iOS needed to be built using WebKit and WKWebView. Those were the rules, and in my opinion, good ones, as they ensure anyone downloading a browser on iOS would get as much security as possible; but the rules changed recently. In any case, I still believe in WebKit and for me there is no better alternative.

On macOS there was always the possibility to use a different browser engine, but considering most web browsers are NOT even on the Mac App Store, and NONE of the mainstream ones are, I consider it an statement to publish a browser built using WebKit and supporting most of the functionality that a mainstream browser does.

A world in itself

WebKit is infamous for its complexity, there are many things happening there and we, as third party developers, have minimum access to them. We don’t have control over everything, we can’t configure out many things, and there are always processes running on the background that we can’t even observe. Folks could base their PhD dissertation on the art of debugging WKWebView.

WebKit is one of the lowest level frameworks on Apple ecosystems, and also one of the hardest to work with, even using UIKit (on AppKit being even harder).

The bridge

WKWebView is a subclass of UIView/NSView, to use it on SwiftUI we need to do it through UIViewRepresentable, NSViewRepresentable or NSViewControllerRepresentable. On this case made sense to use NSViewRepresentable, as we don’t need a NSViewController.

Browser tabs

Each tab on the browser is represented by a different WKWebView, displayed using one of the representable alternatives. When switching to a different tab the WKWebView is removed from being displayed, but it keeps being retained in memory, it will be added to a representable again when it is time to show it once more.

This had been working as expected for years, until…

Bug

On macOS, while visiting Reuters, then switching tabs, and coming back to Reuters, the screen becomes blank, completely empty. No error thrown, no exception, no warning, all the other tabs keep working.

Exploration

Debugged the issue for a whole week, unable to get any information, or to prevent the bug from keep happening. Reproducible 100% of the time, but only for that website.

WKWebView just becomes completely irresponsible, the NSView properties can be accessed, for example frame and isHidden, needsLayout, draw(dirtyRect:), etc. And nothing seems to work to bring back the web view to work.

evaluateJavaScript(_:completionHandler:) doesn’t work anymore, reload(), nor any other of WKWebView’s methods respond either.

Inspecting

The JavaScript console stops responding, there is no error or exception shown, it just goes blank and shows an empty screen with empty content.

Hypothesis

I have only seen it happening on macOS, on iOS this works as expected.

It only seems to happen on reuters.com so far, but my theory is that this will happen on other websites, maybe it is due to a specific web library they use, maybe some UI/React framework, maybe some other dependency.

If it happens in reuters.com I can safely assume it will also happen on many other websites, but I just haven’t been lucky enough to stumble onto them.

To make it clear, for sure it is an issue on my browser, and not on reuters.com

Solution

Replacing NSViewRepresentable by NSViewControllerRepresentable fixed the issue. I’m not exactly sure how or why, but this issue is not there anymore.

To make it compatible, I wrap WKWebView in a basic NSViewController. Such a small price to pay considering the severity of the bug it fixes.

Before

Using NSViewRepresentable

func makeNSView(context: Context) -> some NSView {
    webView
}

After

Using NSViewControllerRepresentable

func makeNSViewController(context: Context) -> some NSViewController {
    let controller = NSViewController()
    controller.view = webView
    return controller
}

Explanation

Attempting to explain it

The inner workings of SwiftUI remain hidden to this day, and we still don’t understand many things that happen under the hood.

When we use a variant of the representables, either UIViewRepresentable, NSViewRepresentable or NSViewControllerRepresentable, we have even less control and information over what is happening.

And there is, to my point of view, a discrepancy between UIViewRepresentable and NSViewRepresentable, such that some scenarios that are completely functional on one won’t necessarily be on the other. Hopefully, when building for macOS we have an alternative.

Conclusion

While I believe is highly unlikely many developers will face the same issue I was facing, as seems a fairly isolated edge-case, using WKWebView, and on just very few websites (I have only found 1 so far), I’m positive the issue could be manifested on other cases, using different subclasses of NSView or UIView.

If you ever find yourself struggling to understand why your NSViewRepresentable stopped working without any explanation, try to use a NSViewControllerRepresentable and maybe your issue will be no more.

Let me know if you have any question.

Starting on iOS 16.4 it is now necessary to opt-in to enable Safari Web Inspector on a WebKit-based app.

Before this version, it was possible to inspect and use Safari Developer Tools in macOS on any iOS app with WebKit, but now we have to turn on the property isInspectable in our WKWebView.

Same behaviour for the iOS Simulator and real devices. While Safari on iOS keeps being inspectable as before.

Turn it on

wkWebView.isInspectable = true

This is a great improvement, as we can now control if we want to enable/disable inspecting; a little communication on the change would have been appreciated, though, not to deal with surprises.

Context menu

iOS presents a context menu when selecting text on some views, like UITextView and WKWebView.

UIResponder protocol allows us to edit the context menu before being presented, with the method buildMenu(with:).

Search Web

Among the options presented on the context menu, there is one for doing a web search of the selected text; indeed very convenient for most cases.

Default browser

Starting on iOS 14, third-party apps can become a default browser, and most web navigation will go through them, this is a “newish” feature and still not bulletproof or mature, though.

While there is a defined way to receive web navigation, i.e. a URL with http or https scheme, there is no scheme, protocol, or deep link defined for web searches, yet.

The problem

Search Web option of the context menu does not know how to tell the default browser to do a web search; in fact, it is possible that app doesn’t have any searching capabilities, as this was not a requirement to become default browser; so this chore will go directly to the only app that for sure can fulfil it: Safari.

But maybe this is not ideal if your app can take care of it.

UIMenuBuilder

As mentioned above, we can intercept and edit a context menu before being presented, so the natural approach would be to edit the UIMenuBuilder object received on buildMenu(with:); but wait, Search Web is not there… yet.

UIMenuBuilder contains a collection of menus, each one of them with a collection of UIMenuElement, some of them are a UICommand or a UIAction.

Interestingly enough, among the menus, we can find the Lookup menu (with the menu identifier lookup), and this has the children Look Up, Find Selection and Translate; if we remove Look Up from the collection, then Search Web will not appear on the context menu at all. But that means losing the Look Up capabilities, which I like a lot.

How can we remove Search Web without removing Look Up?

Solution

The system edits the context menu before being presented and after giving you the chance to edit it on buildMenu(with:), if there is a menu with the identifier lookup and with a UICommand that has the selector _define:, then it will insert the Search Web option, which is a UIAction.

More specifically, it will replace the items on the menu with the same items + Search Web.

Let’s prevent this replacement then.

Subclass UIMenu

Override replacingChildren(_:) with an implementation that does nothing.

class MyMenu: UIMenu {
    override func replacingChildren(
                     _ newChildren: [UIMenuElement]) -> UIMenu {

        return self
    }
}

Replace Look Up

Use your UIMenu subclass configured with the properties of the Look Up menu.

override func buildMenu(with builder: UIMenuBuilder) {
    guard let lookUp = builder.menu(for: .lookup) else { return }

    let myMenu = MyMenu(title: lookUp.title,
                        identifier: lookUp.identifier,
                        options: lookUp.options,
                        children: lookUp.children)

    builder.replace(menu: .lookup, with: myMenu)
}

Extra points

Once Search Web is removed, you could add your implementation for web searching with your own UICommand or UIAction; after all, having this on a context menu is quite handy.

When combining SwiftUI and AppKit you will probably want to participate in the responder chain provided by NSResponder on macOS.

onCommand(_:perform:) view modifier allows us to listen for a Selector and perform an action. In theory, we should be able to use the full power of NSReponder with this, however, depending on the content of your View, you may or may not receive those events, for instance TextField receives them while Toggle doesn’t, not even after applying focusable(_:) modifier; which makes this solution not reliable at all, especially considering that you might change the View without realising that it will break your responder chain.

This is even more noticeable when presenting a View as a sheet, for sheets are modal, and there will be no way for the user to dismiss it and continue using your app.

An alternative is to subclass NSHostingController and listen to events with AppKit.

Example

SwiftUI View

struct MyView: View {
    var body: some View {
        Text("hello world")
    }
}

Subclassing NSHostingController

In this example MyController is listening to cancelOperation(_:) to dismiss itself. This event will be fired, for example, when the user presses ⎋ (Escape key).

class MyController<V>: NSHostingController<V> where V : View {
    override func cancelOperation(_ sender: Any?) {
        presentingViewController?.dismiss(self)
    }
}

Presenting as sheet

guard let parent = window?.contentViewController else { return }
parent.presentAsSheet(MyController(rootView: MyView()))

With this approach, it is also possible to listen to other key and mouse events.

When using classes we have the limitation of not being able to use Self as a parameter for a method, even though we can perfectly use it as a return value.

We have 2 options:

• Replace Self by the name of our class, as Xcode correctly points out in Image 1; however, we loose the power of Generics, if this class is meant to be subclassed.

• Using value types instead of reference types; this limitation is not present on value types as they can’t be inherited.

It is important to be aware of this limitation as Xcode seems to have a hard time understanding what we are trying to do when using Self, and if our method is complex enough we won’t be able to see a descriptive and helpful error message. As it is the case in Image 2, seen below.

With those kinds of undescriptive error messages it may take us a few hours to realise where we went wrong, I know it because this just happened to me, again.

It is only when your reference type and your method are simple enough that you receive a helpful error message from Xcode, as in Image 3; after this, it all makes sense.

While the :has() selector is supported on Safari starting with the version 15.4, this appears not to be the case with content blockers that we can define using WebKit both as an app extension for Safari or inside our app embedded to a WKWebView using a WKContentRuleListStore.

Is important to be aware of this limitation as it will make the entire CSS selector of our content blocker fail (but the rest of the content blocker will still work).

:has()

This is a functional CSS pseudo-class we can use to build complex CSS selectors nesting a relative selector to another, or in other words, if a parent element contains a child element.

Problem

You have some text you want to display and you know exactly how much space you should need to fit this text in, so you create an NSTextField to display it in macOS with AppKit, and you realise it works as expected for most strings but not for all of them, as a few seem to be not fitting properly by just 1 pixel; try roundedBezel for NSTextField.bezelStyle instead.

Bezel

Turns out is not enough to configure an NSTextField.isBezeled = false when using it just to display some text without the user being able to edit it. By default the bezelStyle is set to squareBezel, and this seems to be not using the whole width of the frame of the field itself, while roundBezel seems to do it properly.

Example

NSParagraphStyle

Create a paragraph style so that you can control with precision how the text should be rendered.

let paragraph = NSMutableParagraphStyle()
paragraph.lineBreakMode = .byWordWrapping
paragraph.lineBreakStrategy = .pushOut
paragraph.allowsDefaultTighteningForTruncation = false
paragraph.tighteningFactorForTruncation = 0
paragraph.usesDefaultHyphenation = false
paragraph.defaultTabInterval = 0
paragraph.hyphenationFactor = 0
paragraph.lineSpacing = 1
paragraph.minimumLineHeight = 1
paragraph.maximumLineHeight = 100

NSAttributedString

Create an attributed string and configure it with your paragraph style and font.

let font = NSFont.preferredFont(forTextStyle: .body)

let attributes: [NSAttributedString.Key : Any] = [
            .font: font,
  .paragraphStyle: paragraph]]

let attributedString = NSAttributedString(
                             string: myString, 
                         attributes: attributes)

Height

Get the height you need to display your attributedString by using boundingRect(with:options:context:) instance method of NSAttributedString.

let width = 200.0

let size = CGSize(width: width, 
                 height: .greatestFiniteMagnitude)

let options: [NSString.DrawingOptions] = [
     .usesFontLeading,
     .usesLineFragmentOrigin,
     .truncatesLastVisibleLine,
     .usesDeviceMetrics]

let rect = attributedString
     .boundingRect(with: size
                options: options)

let height = ceil(rect.height)

NSTextField

Create your NSTextField and put everything together.

let field = NSTextField()
field.isBezeled = false
field.bezeStyle = .roundedBezel
field.isEditable = false
field.attributedStringValue = attributedString
field.frame.size = .init(width: width, height: height)

Progress

Progress objects are very handy for monitoring or conveying information of a task that might take a while to complete.

We can use progress objects at our convenience, and sometimes we have no other option but to depend on them; such is the case with WKDownload objects.

I have stumbled several times already, over the past couple of years (WKDownload was only added to WebKit on iOS 14.5 and macOS 11.3) trying to monitor a downloading in progress and displaying sufficient information on the app; mainly because every time I need to update that part of the code I tend to forget what I learned the previous times, so I write it here hoping next time I can remember.

You can use Combine and subscribe to the publishers of a Progress object’s properties, but some of them will publish as expected, some of them will publish constantly, even if there are no changes, and some will never publish at all.

Properties

Progress has many properties available, but not all of them contain information when working with a WKDownload. The ones that I find myself monitoring are:

• fractionCompleted publishes constantly, generally with changes.

• completedUnitCount publishes constantly, generally with changes.

• totalUnitCount publishes constantly, even without any change.

• localizedDescription publishes constantly, even without any change.

• isFinished publishes only when there are changes.

• fileURL does NOT publish, even if there are changes.

Example

Subscribing to a Progress property with Combine, in this case, the progress of a WKDownload object:

var subscription = wkDownload
    .progress
    .publisher(for: \.fractionCompleted)
    .sink { fraction in
        // fraction is a Double
        // with values from 0 to 1
    }

A few days ago I deleted a file in my project, then added it again, after that I renamed it, to finally commit it with Xcode’s Source Control.

Since then and for a few days Xcode was constantly crashing, on a span of every 3-8 minutes; at first I thought it was the app I’m developing behaving weirdly, then I found out it still happened even without having an app running.

I couldn’t understand exactly what the problem was by looking at the logs, but I did notice all of them had the same issue:

Crashed Thread: Dispatch queue: DVTSourceControlGitXPCClient :: Proxy Completion Queue

The part of DVTSourceControlGitXPCClient gave me a hint: it had to do with source control, and specifically with git.

I opened the Terminal, navigated to my project’s repository, asked git status, and there it was: that file I deleted, renamed and committed a few days ago was showing as modified.

Did a staging of all changes, committed them, and since then I haven’t had any more crashes (so far).

I have to say is not the first time I notice some limitations on the way Xcode interacts with git; renaming, and specifically, case-sensitive renames are always an issue.

In case you are having a similar experience with Xcode (14.2 (14C18) in my case), I recommend to try staging everything directly from Terminal and see if it fixes your issue.

Example:

$ cd /myProjectApp
$ git status
$ git add .
$ git commit -m "Cleaning state"

Starting on iOS 15.4 and macOS 12.3 WKPreferences has the new property isElementFullscreenEnabled, part of WKWebViewConfiguration, which enables JavaScript to make elements full-screen in a WKWebView, but it comes with some caveats.

macOS

On macOS is simple; set it true to play videos on full-screen and make any other HTML element full-screen via JavaScript.

myWebView.configuration.preferences.isElementFullscreenEnabled = true

iOS

On iOS, though, setting `isElementFullscreenEnabled = true` disables screen rotation while playing videos on full-screen for apps that only support Portrait Orientation.

This is important if you have an app that only supports portrait orientation but wants screen rotation when playing a video on full-screen (going back to portrait when the video finishes).

With isElementFullscreenEnabled = false, you can still play videos on full-screen (at least on YouTube), and rotate videos, but disables making other HTML elements full-screen.

The first times I decided to debug it, but couldn’t ever manage to reproduce it, so instead tried to convince myself it was somehow fixed by some of the other changes applied (one of those days feeling overly optimistic), as the code base is being updated constantly.

Last night it happened again and I decided it was time to get to the bottom of this; after lots of testing I managed to find a reproducible path for this behaviour, some more testing and I found how to overcome it, and then I realised it is not the first time I find this exact same challenge, so I decided to write about it, hoping I remember the learnings for next time.

The unexpected behaviour can be seen on the next picture:

On the left side is possible to appreciate how the List should be displayed. On the right side there is the same List but some elements are duplicated and the List seem to be broken. Notice for example how the section header for Browser is missing on the right.

The List is built with SwiftUI, and it is using a Published property in an ObservableObject. A extremely simplified representation of the code looks like this:

// Observable
class MyObservable: ObservableObject {
    @Published var items = [Item]()
}

// List
List {
    FirstSection(observable: observable)
    SecondSection(observable: observable)
}

// FirstSection
@ObservedObject var observable: MyObservable
...
Section {
    ForEach(observable.items) { item in
        ...
    }
}

The unexpected behaviour was happening after a very specific set of alterations done in a certain order to the Published property items, these alterations involved adding and deleting items, this very specific case was what made reproducing the bug quite a challenge.

If instead of using the Published property of the ObservedObject for the ForEach in the Section view, a property is used then the List has a better chance of updating itself whenever there are changes:

// List
List {
    FirstSection(items: observable.items)
...

// FirstSection
let items: [Item]
...
Section {
    ForEach(items) { item in
        ...
    }
}

The reason for these 2 different behaviours come from the way SwiftUI updates the interface: when using the Published property from the ObservedObject to display items SwiftUI tries to update only those items that change; when using a property SwiftUI invalidates the whole View (or in this case the List Section) when the value of that property changes.

This comes with some limitations, as it means that the ForEach cannot be created from a Binding and it cannot provide a content closure with individual bindings for each element, a great post from Paul Hudson for what I’m referring to.

This seems to have fixed the unexpected behaviour, but will keep an eye just in case it happens again.

Feedback and comments always welcome.