[Refactoring] Refactoring of theme with wrappers, update documentations

[pylapp]

Context

Today, it is the duty of a theme to embed, override and provide any raw tokens, semantic tokens and future component tokens. It implies to have finaly a class with thousands of objects.

Indeed this is acceptable because the logic behing OUDS is based on themes which are in fact combinations of values for any tokens.

Today a theme is a Swift class which is not a singleton because we don't want to instanciate such massive objects if we don't use it. Using a singleton won't help to override classes so as to have subthemes.

Howeer we can agree that having thousands properties in one object does not bring a good developer experience (DX), and we may implement another solution with wrappers.

Proposal

We may in fact define as many wrappers as "family" of tokens, i.e. ColorsWrapper, BorderWrapper, TypographiesWrapper, DimensionsWrapper etc. Each wrapper must implement (in the same way as the actual implementation of a theme) a protocol to embed specific items of tokens which will be still overridable. Thus a theme won't implement such protocols anymore but will have inside it all wrappers.
If a theme must be subclasses, it should only create a subclass of a wrapper and add it to the theme.

If could result to something like:

// Basic use

open class MyTheme {

    let colors: ColorsWrapper
    let borders: BordersWrapper
    ...

    init(colors: ColorsWrapper, borders: BordersWrapper() {
        self.colors = colors
        sef.borders = borders
    }
}

open class ColorsWrapper: ColorsSemanticTokens {
    // Implement tokens
}

// Alternative use

final class CustomTheme: MyTheme {

    // Init super
    init() {
        super.init(colors: MyColorsWrapper(), borders: BordersWrapper())
    }
}

final class MyColorsWrapper: ColorsWrapper {
    // Override the semantic token we want
}

Then the old line may move to something else:

// Before
theme.buttonBackgroundColorEmphasisHigh
// After
theme.colors.buttonBackgroundEmphasisHigh // If we suppose we wrap it in a "ColorsWrappers" and not a component token

Way may focus to this topic later when we'll have components tokens and tokens to implement.
This solution is quite elgant and may improve DX buy we may face isues with memory and performances because we keep using plenty of Swift classes in the end.

Definition of Done

• Migrate OUDSTheme+BorderSemanticTokens
• Migrate OUDSTheme+OpacitySemanticTokens
• Migrate OUDSTheme+ColorMultipleSemanticTokens (same wrapper as the one as simple colors)
• Migrate OUDSTheme+ColorSemanticTokens (same wrapper as the one with multiple colors)
• Migrate OUDSTheme+ElevationCompositeSemanticTokens (same wrapper as the one with multiple and simple elevations)
• Migrate OUDSTheme+ElevationMultipleSemanticTokens (same wrapper as the one with composite and simple elevations)
• Migrate OUDSTheme+ElevationSemanticTokens (same wrapper as the one with composite and multiple elevations)
• Migrate OUDSTheme+FontCompositeSemanticTokens (same wrapper as the one with multiple and simple font tokens)
• Migrate OUDSTheme+FontMultipleSemanticTokens (same wrapper as the one with composite and simple font tokens)
• Migrate OUDSTheme+FontSemanticTokens (same wrapper as the one with multiple and composite font tokens)
• Migrate OUDSTheme+GridSemanticTokens
• Migrate OUDSTheme+GridSemanticTokensHelper
• Migrate OUDSTheme+SizeMultipleSemanticTokens (same wrapper as the one with simple size tokens)
• Migrate OUDSTheme+SizeSemanticTokens (same wrapper as the one with multiple size tokens)
• Migrate OUDSTheme+SpaceMultipleSemanticTokens (same wrapper as the one with simple space tokens)
• Migrate OUDSTheme+SpaceSemanticTokens (same wrapper as the one with multiple space tokens)
• Check if @objc can be removed, and more documentation about that if not
• Update OrangeTheme init to let users to use their own wrappers
• Update InverseTheme init to let users to use their own wrappers
• Update CHANGELOG
• Update wiki (how to define theme and override tokens)
• Update wiki (charts about architecture)
• Update demo app (use of wrappers through theme)
• Update all tests (use of wrappers through theme)
• For each wrapper, ensure the documentation about its use and the override is enough
• Update DocC catalogs about themes and wrappers
• Provide a sample app, using OUDS as a dependency, with a local theme overriding only some tokens, so as to check if everything is ok

Note that when migrations are done, contact the @boosted-bot tokenator team to have an update on ther side to make PR with our new architecture (no need to wait for tests and doc updates).

[pylapp]

Find attached a kind of quick-and-dirty PoC with a local theme, inheriting from OrangeTheme, and using the enw wrappers overriding some tokens (space, size, color, border, elevation, opacity, grid and font).
The architecture works!

cc @ludovic35

OUDS PoC 79.zip