Rework adornments [Multiple, Start+End, Reusable, etc]

[danielchalmers]

Feature request type

Enhance component

Component name

No response

Is your feature request related to a problem?

Adornments are

• Hard to maintain because of the number of properties needed
• Not documented enough
• Have too much padding as buttons
• Can only be in one place: at start or end

Describe the solution you'd like

A total rework of the adornment system.

Icons

• Can be either a static icon, icon button, static text, or text button
  • All should have similar amount of padding, not the drastic difference we have now
  • Autocomplete: Adornments are styled as Icon Buttons #8878
• Use the small IconButton padding (New Dense property in IconButton)
• Remove IconSize and make it medium to reduce complexity of implementation and to maintain style
• Make the Clear button medium for consistency (Was small)

Positioning & Usage

• Delete MudBaseInput.Adornment & Adornment.cs
• Promote internal MudInputAdornment.razor to public MudAdornment.razor
• Replace other adornments properties in inputs with RenderFragments for Start and End
  • Adornments: Allow for Start & End Adornments on MudInput types (#3658) #7268
• The fragment will let you add as many adornments as you want on each side

Infrastructure

• Add dedicated docs page for MudAdornment with examples of it in use with other components
  • Alternatively we demo it in the pages for the components themselves like we do now
• Add dedicated tests class

Considerations

• Delete the clear button stuff and replace it with a ClearAdornment.razor that users can add themselves
• Do we let any content in a fragment? (ex: chips)
  • And in that case do we avoid all the complications and skip the dedicated MudAdornment component?
• Accessibility 💯

Mock code

MudInput.razor.cs

[Parameter]
public RenderFragment StartAdornmentFragment { get; set; }

[Parameter]
public RenderFragment EndAdornmentFragment { get; set; }

ClearAdornment.razor

@using MudBlazor

<MudIconButton Icon="@Icons.Filled.Clear" OnClick="@ClearInput" Size="Size.Medium" Dense="true" />

@code {
    [Parameter]
    public EventCallback ClearInput { get; set; }
}

AdornmentUsageExample.razor

<MudTextField T="string" Label="Enter text" Variant="Variant.Filled">
    <StartAdornmentFragment>
        <MudAdornment Icon="Icons.Filled.Menu" Size="Size.Medium" Color="Color.Primary" AdornmentClick="@(() => OnAdornmentClick("Start"))" />
    </StartAdornmentFragment>
    <EndAdornmentFragment>
        <MudAdornment Icon="Icons.Filled.Search" Size="Size.Medium" Color="Color.Secondary" AdornmentClick="@(() => OnAdornmentClick("End"))" />
    </EndAdornmentFragment>
</MudTextField>

Have you seen this feature anywhere else?

https://mui.com/material-ui/api/input-adornment/
https://mui.com/material-ui/react-text-field/#input-adornments

Describe alternatives you've considered

No response

Pull Request

• I would like to do a Pull Request

Code of Conduct

• I agree to follow this project's Code of Conduct

[github-actions]

Thanks for wanting to do a PR, @danielchalmers !

We try to merge all non-breaking bugfixes and will deliberate the value of new features for the community. Please note there is no guarantee your pull request will be merged, so if you want to be sure before investing the work, feel free to contact the team first.

[danielchalmers]

@henon @ScarletKuro Thoughts?

[dennisrahmen]

That sounds like a dream.

The clear button I am a bit split about, you gain the ability to completely customize it but might be a bit to much for simple use cases.

Using a nullable value and just having to set one property is really simple.

Also some browser add clear buttons on there own, so the user is already trained to find the cear button at the end of the field.
So there is not really an alternative to the placement I would think.

[henon]

Yes, but let's make it simply StartAdornment and EndAdornment, we never use Fragment only Content but here I'd go for simplicity. This is how that looks:

<MudTextField T="string" Label="Enter text" Variant="Variant.Filled">
    <StartAdornment>
        <MudAdornment Icon="Icons.Filled.Menu" Size="Size.Medium" Color="Color.Primary" AdornmentClick="@(() => OnAdornmentClick("Start"))" />
    </StartAdornment>
    <EndAdornment>
        <MudAdornment Icon="Icons.Filled.Search" Size="Size.Medium" Color="Color.Secondary" AdornmentClick="@(() => OnAdornmentClick("End"))" />
    </EndAdornment>
</MudTextField>

• Promote internal MudInputAdornment.razor to public MudAdornment.razor
• Replace other adornments properties in inputs with RenderFragments for Start and End

Both a good idea. People can move these properties straight to the MudAdornment when migrating.

• The fragment will let you add as many adornments as you want on each side

Awesome. I still think for the name singular (StartAdornment) is better than plural (StartAdornments) as 99% of use-cases will be a single adornment. Having an example that shows that multiple adornments are possible is enough, no need for the name to express this possibility.

• Delete the clear button stuff and replace it with a ClearAdornment.razor that users can add themselves

I'd rather keep the Clearable parameter that automatically adds a ClearAdorner at the end unless the user overrides the EndAdornment. RenderFragments can be null so we can continue to show the existing clear button if the EndAdornment is not set.

• Do we let any content in a fragment? (ex: chips)

Yes of course!

[danielchalmers]

@henon If we want to support all types then does it make sense to skip MudAdornment altogether and make it like this:

<div class="d-flex">
    <MudTextField @bind-Value="Amount" Label="Amount" Variant="Variant.Text">
        <AdornmentStart>
            <MudIcon Icon="@Icons.Material.Filled.AttachMoney" />
        </AdornmentStart>
    </MudTextField>
    <MudTextField @bind-Value="Weight" HelperText="Weight" Variant="Variant.Text" Class="mx-8">
        <AdornmentEnd>
            <MudText> Kg </MudText>
        </AdornmentEnd>
    </MudTextField>
    <MudTextField @bind-Value="Password" Label="Password" Variant="Variant.Text" InputType="@PasswordInput">
        <AdornmentEnd>
            <MudIconButton Icon="@PasswordInputIcon" Edge="Edge.End" OnClick="ButtonTestclick" AriaLabel="Show Password" />
        </AdornmentEnd>
    </MudTextField>
</div>
<div class="d-flex">
    <MudTextField @bind-Value="Amount" Label="Amount" Variant="Variant.Filled">
        <AdornmentStart>
            <MudIconButton Icon="@Icons.Material.Filled.AttachMoney" Edge="Edge.Start" />
        </AdornmentStart>
    </MudTextField>
    <MudTextField @bind-Value="Weight" HelperText="Weight" Variant="Variant.Filled" Class="mx-8">
        <AdornmentEnd>
            <MudText> Kg </MudText>
        </AdornmentEnd>
    </MudTextField>
    <MudTextField @bind-Value="Password" Label="Password" Variant="Variant.Filled" InputType="@PasswordInput">
        <AdornmentEnd>
            <MudIconButton Icon="@PasswordInputIcon" Edge="Edge.End" OnClick="ButtonTestclick" AriaLabel="Show Password" />
        </AdornmentEnd>
    </MudTextField>
</div>
<div class="d-flex">
    <MudTextField @bind-Value="Amount" Label="Amount" Variant="Variant.Outlined">
        <AdornmentEnd>
            <MudIconButton Icon="@Icons.Material.Filled.AttachMoney" Edge="Edge.End" />
        </AdornmentEnd>
    </MudTextField>
    <MudTextField @bind-Value="Weight" HelperText="Weight" Variant="Variant.Outlined" Class="mx-8">
        <AdornmentEnd>
            <MudText> Kg </MudText>
        </AdornmentEnd>
    </MudTextField>
    <MudTextField @bind-Value="Password" Label="Password" Variant="Variant.Outlined" InputType="@PasswordInput">
        <AdornmentEnd>
            <MudIconButton Icon="@PasswordInputIcon" Edge="Edge.End" OnClick="ButtonTestclick" AriaLabel="Show Password" />
        </AdornmentEnd>
    </MudTextField>
</div>

Takes a bit of extra setup but is a lot more flexible and easier to maintain

[danielchalmers]

some browser add clear buttons on there own, so the user is already trained to find the cear button at the end of the field. So there is not really an alternative to the placement I would think.

@dennisrahmen I think you're both right that it should be a bool for ease of use 💯 Do you have any thoughts on the sample code I posted in my last comment? Basically skipping the rigid adornment type altogether so you can use chips etc

[dennisrahmen]

@danielchalmers I think your idea with directly adding the other components is good but I would at least have one MudAdornment that can be a Icon or IconButton for the simple usecases.

For example the MudIcon I just added the Disabled parameter so with the context inside AdornmentEnd I can disable the icon when the field is disabled but then there is ReadOnly so I need to add that as well to the disabled property of the icon.

So when I just want a icon at the end of my form and nothing else I would use MudAdornment and don't have to deal with all that setup.

[dennisrahmen]

Oh, and does this work well with all the margins/padding of for example the MudIconButton?
Because if the fields then all have different heights I don't think this will get much used.

For example having a Icon at the start and a chip or icon button at the end.

[danielchalmers]

@dennisrahmen Great points. I was thinking we can use cascading values like the MudForm to pass down disabled, readonly, etc.
The padding is definitely an issue. ToggleGroup is the only one that is on track to smoothly scale #8676. Not sure how it's going to look if we put other elements in there, but we would at least center them vertically.

Maybe we should pick a few elements that make sense and build them directly into MudAdornment. But how do pass the information to it as a renderfragment except for cascading? Which elements would we want as adornments?

[ScarletKuro]

I was thinking we can use cascading values like the MudForm to pass down disabled, readonly, etc.

We better merge it into a single class that holds it, otherwise multiple mutable cascading values will hit the performance really hard.

[henon]

Yep. For instance, we already have RightToLeft cascading parameter that permeates all GUI. We could go from this to an extensible cascading context with properties for RightToLeft , Disabled, Theme etc. We could even add a Parent property that stores the parent cascading context if it gets overridden by a child.

[danielchalmers]

@henon @ScarletKuro Interesting, didn't know that. Do you have thoughts on how to actually write the implementation for that and the new adornment system? Should I spin it off into a separate issue? I'm a bit lost atm but would like to give it a shot

[henon]

It is just an optimization and can be done separately. Let's not loose ourselves in the details, focus on the adornment render fragments first and the optimization can be done later.

[danielchalmers]

@henon I guess it won't work though because IconButton doesn't have any CascadingParameters

[henon]

We can always add them if needed.

[danielchalmers]

We can always add them if needed.

@henon Wouldn't that mean we would have to set CascadingParameters on all basic components in the library in case they want to be used as adornment (obviously not ones like Dialog, Picker, Table)?

[dennisrahmen]

We should not forget all the edge cases.
For example Icons have Disabled as property but no ReadOnly so cascading parameters would not help here since we would need to map the ReadOnly from the field to the Disabled of the icon.

I would keep this simple for now with the adornment that supports a few basic components like icon and icon button and a context that can be used if someone want to add a chip or other components as adornment.

[henon]

@henon Wouldn't that mean we would have to set CascadingParameters on all basic components in the library in case they want to be used as adornment (obviously not ones like Dialog, Picker, Table)?

Hmm, we can support Disabled in those that are most likely used but we can also pass the same info down into the render fragement via a context variable so the users can use them in their custom RF.

[henon]

Or maybe that is overkill. They would know themselves if their input is disabled.

[dennisrahmen]

Or maybe that is overkill. They would know themselves if their input is disabled.

Yes they would know, but I for example mostly set that for the hole form not for individual components.

So with the context that would cascade down from the form to the field to the custom adornment they used the context in.

When there is no context they/I would need to remember when setting disabled in the form to also set it when using a custom adornment.