Trying to understand NS_REFINED_FOR_SWIFT when used on a whole class

I am working on a framework project written in Objective-C. I'm trying to ensure the resulting public Swift API follows modern standards. As a result I'm looking into macros such as NS_SWIFT_NAME and NS_REFINED_FOR_SWIFT. I've been through Apple's documentation for Objective-C and C Code Customization. But they only have one example using NS_REFINED_FOR_SWIFT and it's at the method level.

I happen to be looking at some of the Apple header files in the CloudKit framework, specifically for the new CKSyncEngine related types. I noticed that every Objective-C class is prefixed with NS_REFINED_FOR_SWIFT. Since now every class name and method name is hidden with the double-underscore prefix, I imagine that this means that there is more than just a simple Swift class extension to help better map the method and property names.

What I need help with is a starting example when several Objective-C classes are marked with NS_REFINED_FOR_SWIFT. What Swift code must be provided in the framework to properly expose those refined class names?

Let's start with an example that looks a lot like UIButton and UIButton.Configuration. The Objective-C header file might look like this:

NS_REFINED_FOR_SWIFT
@interface MyButtonConfiguration: NSObject

@end

NS_REFINED_FOR_SWIFT
@interface MyButton: UIControl

- (instancetype)initWithConfiguration:(MyButtonConfiguration *)configuration NS_SWIFT_NAME(init(configuration:));

@end

This is a greatly oversimplified example as a starting point. If the code was really this simple I could easily use NS_SWIFT_NAME on the class names and be done. But I'm trying to understand the starting point for a far more complicated API.

I want to end up with the Swift API having the class names MyButton and MyButton.Configuration (like a nested scope).

If I had not used NS_REFINED_FOR_SWIFT on the whole class, but just some method/properties, then I would add Swift code such as:

extension MyButton {
    func someRefinedAPI() {
        __someOriginalAPI()
    }
}

But having NS_REFINED_FOR_SWIFT at the class level means that MyButton is exposed as __MyButton and MyButtonConfiguration is exposed as __MyButtonConfiguration in Swift. What Swift code do I need to add to my framework to get those refined names exposed as MyButton and MyButton.Configuration?

I tried something like the following:

typealias MyButton = __MyButton // This works
typealias MyButton.Configuration = __MyButtonConfiguration // Gives error at the period with: Expected '=' in type alias declaration

I was going to follow those with the class extensions for the refined methods and properties but I can't get past the starting point of the class names.

So how do you translate an Objective-C classname into a nested Swift type hierarchy when using NS_REFINED_FOR_SWIFT at the class level?

In my real framework there will be Objective-C types that need to become 3rd level nested types in Swift. Think UIButtonConfigurationSize to UIButton.Configuration.Size, for example. NS_SWIFT_NAME doesn't seem to accept names with 3 levels.

NS_REFINED_FOR_SWIFT is used for API's methods that return values by pointer in parameters.
Refined API will return values in tuple instead.

NS_REFINED_FOR_SWIFT can't create nested classes.

Still you can write:

extension MyButton {
    typealias Configuration = __MyButtonConfiguration
}

With the push in the right direction by @Cy-4AH I figured out how to get a 3rd level as well.

For example, if I want the Objective-C class MyButtonConfigurationSize to be exposed as MyButton.Configuration.Size in Swift, then after adding the first extension, I would need:

extension MyButton.Configuration {
    typealias Size = __MyButtonConfigurationSize
}

It seems so obvious now.