Resources & Default Styles

[robloo]

Issue

I wonder how do we prevent #6638 (fixed with #6924) from happening in the future? None of us thought of it as obvious as it is in hindsight. Fundamentally, we have a duplication of themes/default styles issue. For DropDownButton itself there are two default styles

https://github.com/unoplatform/uno/blob/master/src/Uno.UI.FluentTheme/Resources/PriorityDefault/DropDownButton.xaml

and

https://github.com/unoplatform/uno/blob/master/src/Uno.UI/UI/Xaml/Controls/DropDownButton/DropDownButton.xaml

Not to mention other controls likely have a Microsoft.UI.Xaml/Windows.UI.Xaml version of XAML as well -- a total of three places. But wait! We have 2.6 styles incoming meaning a potential of 4 variations in no consistent folders or organizational structure!

More Details

In a little more detail I note the following variations of XAML themes:

1. The original 'XAML' from before WinUI Library, think of this like generic.xaml shipped with Windows. Uno doesn't seem to have a standard convention for organizing resources and styles from this period. You may find them in control folders... or some place else.
2. The WinUI Library version 1 Fluent Theme
   a. For all controls ported from WinUI XAML is copy/pasted in the controls directory.
   b. However, these default style are also located in the FluentTheme project. The logic for determining which to use is unknown.
3. The WinUI Library / WinUI 3 version 2 Fluent Theme. Another variant of XAML that for the most part is also going in control folders. This is likely to turn out the same as number 2 above.

While it makes sense how things got here, it almost certainly doesn't make sense in total for where we are today. Even worse, Uno does not document this at all. This all needs to be cleaned up and documented for contributors.

Code duplication is bad like this as it's very easy to miss updates in both -- not to mention developers will expect the XAML within the Microsoft.UI.Xaml.Controls folder to be what is actually used. Not another version in a FluentTheme Priority folder.

Possible Solution

1. Document in detail how Uno currently processes and uses resources/default styles. Explain the folder structure, the FluentTheme project, the priority folders.
2. Determine an exact methodology for where to place XAML with NO duplication. Again, I understand how things got to be what they are. However, if we have fluent theme XAML in a MUX control folder we dare not put it in the FluentTheme project as well.
   • This is where it would make some sense to create 3 theme projects and allow NO Xaml in code directories like what is done in WinUI upstream.
   • Alternatively, MUX controls should have the default styles in each control's folder -- shared resources/styles in a CommonStyles directory. Then MUX controls should have both fluent v1 and v2 default styles in the controls folders also with a CommonStyles directory matching upsstream WinUI exactly. FluentTheme project shouldn't exist on its own.

[davidjohnoliver]

I definitely agree that this should be better documented for contributors.

Re: duplication: the styles and resources in Uno.UI are the 'framework resources'. The ones in Uno.UI.FluentTheme are bundled with the XamlControlsResources dictionary. If XamlControlsResources is injected in App.xaml, then those ones take precedence according to normal precedence rules.

So unfortunately the duplication is necessary, since we need both sets of styles to conform to what WinUI/UWP are doing.

[robloo]

@davidjohnoliver

the styles and resources in Uno.UI are the 'framework resources'. The ones in Uno.UI.FluentTheme are bundled with the XamlControlsResources dictionary. If XamlControlsResources is injected in App.xaml, then those ones take precedence according to normal precedence rules.

I understand this. However:

1. Uno.UI (except for Microsoft/UI/Xaml) follows no organizational method for resources and styles as far as I can tell. This MUST be standardized somehow whether they are framework resources or not.
2. Microsoft/UI/Xaml is well organized following upstream. However, it's styles can be overridden by those in the Fluent theme -- even though the resources and styles here MUST already be fluent theme both versions 1 and 2. Here specifically XAML in Microsoft/UI/Xaml should be copied into FluentTheme and used with precedence over anything else there.

Finally, even in Windows, framework resources and styles are built from the same source -- they are just merged and copied into the generic.xaml shipped with Windows periodically. Uno really should not be duplicating them and if the files are duplicated (because you keep FluentTheme) it should be automatically done with a single source of truth.

I still think there is an opportunity to split apart all of these xaml files much better. There is no consistent system.

Edit: So while I see a few opportunities to actually remove duplication, if Uno decides to keep the duplication there still should be consistent organizational structure of these files (reorganize Uno.UI to match Microsoft/UI/Xaml) and clear documentation.

[robloo]

Copying the below comment from #6374 (comment) to keep it in this discussion.

---

@robloo you are right, it is probably quite worth documenting 👍 . In short however, the main point of the "Priority" folders is to ensure the files are merged in a order that ensures that the styles that are referenced by other styles occur earlier in the merged file. For example Priority01 contains Common_themeresources as they are referenced almost everywhere. Then AcrylicBrush_themeresources are in Priority02 because they reference things from 01 but are themselves references by things in PriorityDefault for example.

No :D This isn't necessary, XAML supports lexically forward references.

The FluentTheme XAML resources are placed into Priority files according to the value of the Priority attribute in the WinUI repo's project structure. Eg:

https://github.com/microsoft/microsoft-ui-xaml/blob/9052972906c8a0a1b6cb5d5c61b27d6d27cd7f11/dev/Materials/Reveal/RevealBrush.vcxitems#L32-L37

The WinUI repo uses the 'Priority' attribute to determine which resource 'wins' in the case of duplicate resource declarations. So in the case that, say, two different XAML files declare a SplartControlForegroundBrush resource, or a default ListViewItem style, the one with higher priority is the one that actually gets included in the amalgamated themeresources.xaml file. That's done here:

https://github.com/microsoft/microsoft-ui-xaml/blob/bbc4549d65222be8fc9deb128afabb624ae191e9/dev/dll/Microsoft.UI.Xaml.vcxproj#L648-L656

We could probably duplicate in detail what the project system is doing, but to save time I used the trick of just putting them in different folders, which achieves the same thing based on the order in which Uno's XAML generation processes files.

This hopefully partially answers the question @robloo posed in #6926 . :)