Typed Style Properties

[Aeshus]

About the PR

Added new StylePropertyKey<T> type to ensure style properties are correctly set to the right type, and a bunch of warnings to help enforce a better style (e.g. don't hard-code strings as StyleProperty inside of Prop)

Why

I've been doing a lot of stylesheet work recently and I've had a few times where I accidentally set a property to an invalid value, and it would just silently fail within TryGetStyleProperty<T>. Now, when writing stylesheet code, it'll give you better auto-completion for the value for a property as well as compile-time errors when you put an invalid value for a type.

Technical details

The Extract typed style properties commit is the only one with substantive changes, the rest are all either style or fixing warnings.

StylePropertyKey<T> is really just a thin wrapper around a string with a phantom type.

It is possible to bypass the type checking using StylePropertyKey<T> by constructing untyped StyleProperty values directly, as older stylesheet code did this and removing support would cause a breaking change. The string-based key compatibility stuff produces warnings but can't provide type checking.

Memory-wise, it shouldn't be an issue as it's just a struct wrapped around a single string that it implicitly transforms between.

Migration

It generally tends to be that most warnings are because a string is used as a key. Instead of hard-coding a string in the Stylesheet, define a StylePropertyKey<T> field in your Control class (or reuse another Control's) and use it. If you already had a string defined, just change the type.

Here's some examples of diffs to resolve some warnings in Content:

warning CS0618: 'MutableSelector.Prop(string, T)' is obsolete: 'Use Prop(StylePropertyKey, T) with a typed style property key.'

            E<LineEdit>()
                .Class(LineEdit.StyleClassLineEditNotEditable)
-                .Prop("font-color", new Color(192, 192, 192)),
+                .Prop(Label.StylePropertyFontColor, new Color(192, 192, 192)),
            E<LineEdit>()
                .Pseudo(LineEdit.StylePseudoClassPlaceholder)
-                .Prop("font-color", Color.Gray),
+                .Prop(Label.StylePropertyFontColor, Color.Gray),
            E<TextEdit>()
                .Pseudo(TextEdit.StylePseudoClassPlaceholder)
-                .Prop("font-color", Color.Gray),
+                .Prop(Label.StylePropertyFontColor, Color.Gray),

warning CS0618: 'Control.TryGetStyleProperty(string, out T)' is obsolete: 'Use TryGetStyleProperty(StylePropertyKey, out T) with a typed style property key.'

-        public const string StylePropertySeparation = "separation";
+        public static readonly StyleProperty<int> StylePropertySeparation = "separation";

        private const int DefaultSeparation = 0;

        private int ActualSeparation
        {
            get
            {
                if (TryGetStyleProperty(StylePropertySeparation, out int separation))
                {
                    return separation;
                }

                return SeparationOverride ?? DefaultSeparation;
            }
        }

Breaking changes

Content (space-wizards/space-station-14) builds successfully without any changes and any new errors. The build will still succeed unless a type error was already present within the style code.

Changelog

Added a new StylePropertyKey<T> class to be used to define style properties in controls. This provides type safety for styling, but can break builds if type errors are present.

Lots of new warnings for directly using strings instead of StylePropertyKey<T> as StyleProperty keys/names.