Add CSS support for adding Shadows to VisualElement

[sthewissen]

Description

Currently, while all VisualElement objects in .NET MAUI support the Shadow property with attributes such as Offset (x, y), Opacity, Brush (color), and Radius, there is no native support for defining shadows directly through CSS. This feature request proposes the addition of CSS syntax (either through the CSS equivalent box-shadow or a custom MAUI format) and corresponding support for styling shadows in .NET MAUI.

Public API Changes

I would expect the following API changes to be required, please do add to this list as I'm sure it's not entirely complete.

• Add StyleProperty declarations to AssemblyInfo.cs (also unsure whether the PropertyOwnerType setup is correct here).

[assembly: StyleProperty("shadow", typeof(VisualElement), nameof(VisualElement.ShadowProperty))]
[assembly: StyleProperty("shadow-color", typeof(VisualElement), nameof(Shadow.BrushProperty), PropertyOwnerType = typeof(Shadow))]
[assembly: StyleProperty("shadow-offset", typeof(VisualElement), nameof(Shadow.OffsetProperty), PropertyOwnerType = typeof(Shadow))]
[assembly: StyleProperty("shadow-radius", typeof(VisualElement), nameof(Shadow.RadiusProperty), PropertyOwnerType = typeof(Shadow))]
[assembly: StyleProperty("shadow-opacity", typeof(VisualElement), nameof(Shadow.OpacityProperty), PropertyOwnerType = typeof(Shadow))]

• Add TypeConverter to allow conversion from a string to a completely defined Shadow.
• The necessary plumbing to combine the CSS with actually setting the properties and assigning a Shadow object.
• Support for setting only some of the Shadow properties and combining them through multiple CSS classes.

To support setting individual properties we will probably need to come up with a mechanism that can also initialize a Shadow object, given that all the other CSS-related styling is mapping properties whereas this is setting properties of a property. Perhaps something like an attached property setup that could set Shadow.Offset etc?

Intended Use-Case

Using CSS to style the shadows, we could either use it to set a complete shadow in a single line, or use various classes and combine them accordingly through StyleClass to make a shadow. Given that Shadow translates so nicely to CSS, I feel like it's a missing piece that can go a long way to users styling their apps in a modern fashion.

/* Scenario 1: */
.shadow-singleline {
   shadow: 4 4 8 #000000 0.5; /* OffsetX, OffsetY, Radius, Color, Opacity */
}

/* Scenario 2: */
.shadow-md {
    shadow-offset: 4 4; 
    shadow-opacity: 0.5; 
    shadow-radius: 8;
}

.shadow-black {
    shadow-color: #000000;
}

Which would be used as such in XAML:

<Label Text="Single Line Shadow" StyleClass="shadow-singleline" />
<Label Text="Combined Shadow" StyleClass="shadow-md,shadow-black" />

[sthewissen]

I wouldn't mind implementing this myself, but would definitely appreciate some pointers on all the moving parts that are involved in this and whether or not my thinking is correct with this. A potential next step could also be to implement Border and it's styling as well.

[jfversluis]

@StephaneDelcroix ?

[StephaneDelcroix]

@sthewissen feel free to send a PR. what you need to get this working is

• registering a StyleProperty
• change adapt the type converter so it supports the CSS syntax

As I can't find those css properties in the css spec (but I might be wrong), property names should be prefixed (with -maui-).
Don't forget to add Xaml unit tests for it

[sthewissen]

@StephaneDelcroix I think for the variation where you just set a singular fully defined shadow value in CSS that should indeed be most of the work needed. Basically that boils down to the string being interpreted fully and creating a new Shadow object from it. I think the CSS spec has some overlap through box-shadow, but probably not completely. Opacity isn't in there, that is typically set on the alpha channel of the color definition. I'm perfectly fine making a -maui-shadow property for that setup given the CSS spec only partially covers it.

However, the scenario I'm not quite grasping yet is how we could make it so that we can set certain individual shadow-related properties in CSS and have them somehow come together from multiple CSS classes to form a partial Shadow object. I don't think a similar setup currently exists in the CSS setup as it is right now.

[StephaneDelcroix]

we have similar cases of compound properties constructing a single value: font-[family/size/style], padding, margin, etc... it takes a BP for each but I think those could be internal (so the API surface doesn't change)

[sthewissen]

So if I'm correctly understanding what you're saying, a valid solution could be to add the following CSS mappings:

[assembly: StyleProperty("-maui-shadow-opacity", typeof(VisualElement), nameof(VisualElement.ShadowOpacityProperty))]
[assembly: StyleProperty("-maui-shadow-offset-x", typeof(VisualElement), nameof(VisualElement.ShadowOffsetXProperty))]
[assembly: StyleProperty("-maui-shadow-offset-y", typeof(VisualElement), nameof(VisualElement.ShadowOffsetYProperty))]
[assembly: StyleProperty("-maui-shadow-color", typeof(VisualElement), nameof(VisualElement.ShadowColorProperty))]
[assembly: StyleProperty("-maui-shadow-radius", typeof(VisualElement), nameof(VisualElement.ShadowRadiusProperty))]

That would then result in internal bindable properties on VisualElement that set the current shadow's properties (or create a new one if it's null), similar to how Padding works?

[sthewissen]

@jsuarezruiz How do you think we could best implement the individual shadow properties for individual styling? My current thinking is creating an IShadowElement and a ShadowElement that handles all of that which VisualElement will subsequently implement, but I feel like that might be quite a big setup to implement for this.

[mattleibow]

Why do we need the Maui prefix if this is css shadows?

Can we make box-shadow work? Can we just get a converter to take the css and construct the shadow? The opacity in the color we can cotally intercept and make it alpha. Also, do we even need to? What happens if we use a color with alpha for color? It should just draw the color see through and no need for alpha separate..

[sthewissen]

@mattleibow The main reasoning from my side would be that box-shadow has properties that aren't available in .NET MAUI, meaning a 1-to-1 translation of it wouldn't necessarily be possible. In this case those would be spread-radius (which isn't the same as blur-radius) and the inset keyword. Also, I would someday like to add to this that individual properties of the shadow can be influenced by different CSS classes like below, which isn't something box-shadow supports.

/* Scenario 2: */
.shadow-md {
    shadow-offset: 4 4; 
    shadow-opacity: 0.5; 
    shadow-radius: 8;
}

.shadow-black {
    shadow-color: #000000;
}

Regardless, I'm personally fine either way and it's just a matter of renaming the line in AssemblyInfo. I think it mostly boils down to the convention the MAUI team would like to stick to when it comes to what kind of CSS properties get the prefix and which don't.

[mattleibow]

OK, makes sense. Until we get most of box-shadow features supported, the separate ones are fine.