Make ShrinkLabel configurable on MudBlazor field components #177

Problem / motivation

Reported by @bdsoko in #146 after .WithVariant(...) shipped in v3.1.0:

While using, I set the variant to 'Text' and noticed that the label does not float. I believe it's because ShrinkLabel property is hardcoded to 'true'. Any chance this can be customizable as well.

Confirmed. ShrinkLabel="true" is hardcoded at 12 sites across FormCraft.ForMudBlazor, with no way for a consumer to override it:

ShrinkLabel="true" permanently pins the label above the input. That reads correctly for Variant.Outlined (the default, where the label sits in the notch of the border) and acceptably for Variant.Filled. For Variant.Text it removes the one affordance the variant relies on: the label is meant to sit inside the input as a placeholder and float up on focus/value. The result is a floating label over an input that has no border to anchor it — visually orphaned, and exactly what @bdsoko is seeing.

This makes the v3.1.0 Variant feature only two-thirds useful: Variant.Text is selectable but not presentable.

Proposed solution

Make ShrinkLabel configurable through the same channel Variant already uses — a field-level builder extension plus a form-level default, resolved through AdditionalAttributes. The v3.1.0 work built exactly this plumbing (MudBlazorFieldComponentBase.EffectiveVariant, FormCraftCascadingValues.DefaultVariant, FormCraftComponent.DefaultVariant); this rides it rather than inventing a second mechanism.

New public surface, all in FormCraft.ForMudBlazor:

// Field-level (FieldBuilderExtensions) — sibling of WithVariant
.AddField(x => x.Name, field => field
    .WithLabel("Name")
    .WithVariant(Variant.Text)
    .WithShrinkLabel(false))          // label floats on focus/value

// Form-level (FormCraftComponent<TModel>) — sibling of DefaultVariant
<FormCraftComponent TModel="MyModel"
                    Model="@model"
                    Configuration="@config"
                    DefaultVariant="Variant.Text"
                    DefaultShrinkLabel="false" />

Precedence mirrors Variant exactly: field-level wins over form-level, form-level over the built-in default, and the built-in default stays true so no existing form changes appearance.

Alternatives considered

• Derive ShrinkLabel from the variant (ShrinkLabel = variant != Variant.Text) — zero new API and it fixes the reported symptom with no consumer action. Rejected: it is unoverridable magic, it silently changes rendering for anyone already on Variant.Text who wanted the pinned label, and it couples two independent MudBlazor properties forever.
• Form-level parameter only, no field-level extension — smaller surface, but breaks the symmetry with Variant/MinDate/MaxDate and can't express a single field that differs from the form.
• Expose the raw ShrinkLabel attribute via .WithAttribute("ShrinkLabel", false) — already technically possible for renderers reading AdditionalAttributes, but it is undiscoverable, untyped, and today no component reads that key.

Area

FormCraft.ForMudBlazor — field rendering

Related: #146 (the Variant request this follows up on, shipped in v3.1.0), #148 (render-pipeline consolidation that made this well-contained)

namespace FormCraft.ForMudBlazor;

public static class FormCraftCascadingValues
{
    public const string DefaultVariant = "FormCraftDefaultVariant";
    // new
    public const string DefaultShrinkLabel = "FormCraftDefaultShrinkLabel";
}

public abstract class MudBlazorFieldComponentBase<TModel, TValue> : FieldComponentBase<TModel, TValue>
{
    [CascadingParameter(Name = FormCraftCascadingValues.DefaultVariant)]
    public Variant? FormDefaultVariant { get; set; }

    // new
    [CascadingParameter(Name = FormCraftCascadingValues.DefaultShrinkLabel)]
    public bool? FormDefaultShrinkLabel { get; set; }

    protected Variant EffectiveVariant =>
        GetAttribute<Variant?>("Variant") ?? FormDefaultVariant ?? Variant.Outlined;

    // new
    protected bool EffectiveShrinkLabel =>
        GetAttribute<bool?>("ShrinkLabel") ?? FormDefaultShrinkLabel ?? true;
}

public static class FieldBuilderExtensions
{
    // new
    public static FieldBuilder<TModel, TValue> WithShrinkLabel<TModel, TValue>(
        this FieldBuilder<TModel, TValue> builder,
        bool shrinkLabel = true)
        where TModel : new()
        => builder.WithAttribute("ShrinkLabel", shrinkLabel);
}

public partial class FormCraftComponent<TModel>
{
    [Parameter] public Variant DefaultVariant { get; set; } = Variant.Outlined;
    // new
    [Parameter] public bool DefaultShrinkLabel { get; set; } = true;
}

flowchart TD
    A["MudBlazor input needs ShrinkLabel"] --> B{"field's AdditionalAttributes<br/>contains 'ShrinkLabel'?<br/><i>.WithShrinkLabel(...)</i>"}
    B -->|yes| C["use that value<br/><b>field-level wins</b>"]
    B -->|no| D{"cascaded FormDefaultShrinkLabel<br/>has a value?<br/><i>DefaultShrinkLabel param</i>"}
    D -->|yes| E["use the form-level default"]
    D -->|no| F["use <b>true</b><br/>preserves v3.0/v3.1 rendering"]

🛠️ Implementation plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: make MudBlazor's ShrinkLabel configurable per field and per form, resolving to true when unset, so Variant.Text can render a floating label (follow-up to #146).

Architecture: FormCraft core stays UI-framework-agnostic — every change in this plan lands in FormCraft.ForMudBlazor or its test project; nothing in FormCraft/ is touched. Configuration flows one way: FieldBuilder → IFieldConfiguration.AdditionalAttributes → renderer component. The form-level default travels by cascading value, never by service or static state.

Tech stack: .NET 8 / 9 / 10 multi-target, Blazor, MudBlazor, xUnit + bUnit + Shouldly (MudBlazorTestBase).

Global constraints:

• Base branch dev; commit as Philippe Matray <phmatray@gmail.com>; conventional commits (feat:, test:, docs:).
• Default rendering must not change. RenderPipelineParityTests.cs:237 and :257 assert ShrinkLabel.ShouldBeTrue() — they must stay green unmodified. Editing them to accommodate the change means the change is wrong.
• Additive only: no existing public member is renamed, removed, or has its default altered.
• Mirror Variant naming exactly (WithShrinkLabel / DefaultShrinkLabel / FormDefaultShrinkLabel / EffectiveShrinkLabel) — a reader who knows one must be able to predict the other.
• Suite: dotnet test FormCraft.ForMudBlazor.UnitTests/FormCraft.ForMudBlazor.UnitTests.csproj; single class via --filter "FullyQualifiedName~ShrinkLabelConfigurationTests".
• Full dotnet build + dotnet test green before the final commit.

Task 1: Field-level .WithShrinkLabel(...), honored by the text field

Proves the whole chain end-to-end on one component before rolling out.

Files: modify FormCraft.ForMudBlazor/Fields/MudBlazorFieldComponentBase.cs, FormCraft.ForMudBlazor/Extensions/FieldBuilderExtensions.cs, FormCraft.ForMudBlazor/Fields/TextField/MudBlazorTextFieldComponent.razor (line 25); create FormCraft.ForMudBlazor.UnitTests/Fields/ShrinkLabelConfigurationTests.cs.

Interfaces: MudBlazorFieldComponentBase<TModel,TValue>.EffectiveShrinkLabel => GetAttribute<bool?>("ShrinkLabel") ?? FormDefaultShrinkLabel ?? true; FieldBuilderExtensions.WithShrinkLabel<TModel,TValue>(this FieldBuilder<TModel,TValue>, bool shrinkLabel = true).

• Step 1: Write the failing tests in ShrinkLabelConfigurationTests.cs (copy VariantConfigurationTests.cs's class shape and its RenderForm helper): TextField_Should_Default_To_ShrinkLabel_True and WithShrinkLabel_False_Should_Apply_To_TextField, asserting component.FindComponent<MudTextField<string>>().Instance.ShrinkLabel.
• Step 2: Run dotnet test FormCraft.ForMudBlazor.UnitTests/FormCraft.ForMudBlazor.UnitTests.csproj --filter "FullyQualifiedName~ShrinkLabelConfigurationTests" → FAIL (WithShrinkLabel does not exist).
• Step 3: Add FormCraftCascadingValues.DefaultShrinkLabel = "FormCraftDefaultShrinkLabel", the [CascadingParameter(Name = …)] public bool? FormDefaultShrinkLabel, and EffectiveShrinkLabel to MudBlazorFieldComponentBase.cs — XML docs mirroring the Variant members directly above.
• Step 4: Add WithShrinkLabel to FieldBuilderExtensions.cs immediately after WithVariant (line 139), with XML docs whose <example> shows the Variant.Text pairing.
• Step 5: In MudBlazorTextFieldComponent.razor, change ShrinkLabel="true" (line 25) to ShrinkLabel="@EffectiveShrinkLabel".
• Step 6: Re-run the filtered suite → PASS.
• Step 7: Run the full FormCraft.ForMudBlazor.UnitTests suite → PASS, confirming RenderPipelineParityTests is still green with no edits.
• Step 8: Commit: feat(mudblazor): add .WithShrinkLabel field extension honored by text field.

Task 2: Form-level DefaultShrinkLabel + precedence

Files: modify FormCraft.ForMudBlazor/Features/FormContainer/FormCraftComponent.razor.cs (near DefaultVariant, line 53), FormCraft.ForMudBlazor/Features/FormContainer/FormCraftComponent.razor (the cascade at line 12); modify ShrinkLabelConfigurationTests.cs.

Interfaces: FormCraftComponent<TModel>.DefaultShrinkLabel — [Parameter] public bool, default true; cascaded as TValue="bool?" under FormCraftCascadingValues.DefaultShrinkLabel.

• Step 1: Write failing tests: DefaultShrinkLabel_False_Should_Apply_To_Fields_Without_Explicit_Setting, FieldLevel_WithShrinkLabel_Should_Override_FormLevel_DefaultShrinkLabel (field true over form false, and field false over form true).
• Step 2: Run the filtered suite → FAIL (no DefaultShrinkLabel parameter).
• Step 3: Add the DefaultShrinkLabel [Parameter] to FormCraftComponent.razor.cs with XML docs pointing at .WithShrinkLabel(...).
• Step 4: In FormCraftComponent.razor, nest a <CascadingValue TValue="bool?" Name="@FormCraftCascadingValues.DefaultShrinkLabel" Value="@DefaultShrinkLabel"> around the existing Variant cascade — and add the matching closing tag at the end of the markup.
• Step 5: Re-run the filtered suite → PASS.
• Step 6: Commit: feat(mudblazor): add form-level DefaultShrinkLabel parameter.

Task 3: Roll out to the remaining 10 .razor components

Files: modify Fields/NumericField/MudBlazorNumericFieldComponent.razor (22), Fields/NumericField/MudBlazorNullableNumericFieldComponent.razor (22), Fields/SelectField/MudBlazorSelectFieldComponent.razor (18), Fields/SelectField/MudBlazorMultiSelectFieldComponent.razor (18), Fields/DateTimeField/MudBlazorDateTimeFieldComponent.razor (16), Fields/DateTimeField/MudBlazorDateOnlyFieldComponent.razor (15), Fields/DateTimeField/MudBlazorTimeOnlyFieldComponent.razor (15), Fields/AutocompleteField/MudBlazorAutocompleteFieldComponent.razor (18), Fields/LookupField/MudBlazorLookupFieldComponent.razor (16), Features/CustomFields/MudBlazorColorPickerComponent.razor (15); modify ShrinkLabelConfigurationTests.cs.

Interfaces: none new — each site swaps the literal for @EffectiveShrinkLabel.

• Step 1: Write failing per-component tests covering numeric, nullable-numeric, select, multi-select, date-time, date-only, time-only, autocomplete, lookup and color-picker — each asserting default true and .WithShrinkLabel(false) → false. Use the MudPopoverProvider render helper for the picker-backed ones.
• Step 2: Run the filtered suite → FAIL on every component not yet converted.
• Step 3: Replace ShrinkLabel="true" with ShrinkLabel="@EffectiveShrinkLabel" in all 10 files.
• Step 4: Verify none were missed: grep -rn 'ShrinkLabel="true"' FormCraft.ForMudBlazor/ returns nothing.
• Step 5: Re-run the filtered suite → PASS, then the full suite → PASS.
• Step 6: Commit: feat(mudblazor): honor configurable ShrinkLabel in all input components.

Task 4: Collection item fields (RenderTreeBuilder path)

The collection renderer builds its inputs imperatively and resolves Variant through its own helper; ShrinkLabel needs the parallel treatment.

Files: modify FormCraft.ForMudBlazor/Features/CollectionField/CollectionFieldComponent.razor.cs (AddCommonFieldAttributes line 271; add helper next to GetItemFieldVariant line 278); modify ShrinkLabelConfigurationTests.cs.

Interfaces: private bool GetItemFieldShrinkLabel(IFieldConfiguration<TItem, object> field) — reads field.AdditionalAttributes["ShrinkLabel"] as bool, else FormDefaultShrinkLabel ?? true; plus a [CascadingParameter(Name = FormCraftCascadingValues.DefaultShrinkLabel)] public bool? FormDefaultShrinkLabel alongside the existing FormDefaultVariant (line 40).

• Step 1: Write failing tests for a collection field: item inputs default to ShrinkLabel == true, honor a per-item-field .WithShrinkLabel(false), and honor the form-level DefaultShrinkLabel="false".
• Step 2: Run the filtered suite → FAIL.
• Step 3: Add the FormDefaultShrinkLabel cascading parameter and GetItemFieldShrinkLabel, mirroring GetItemFieldVariant's structure exactly; change line 271 to pass the resolved value.
• Step 4: Re-run the filtered suite → PASS, then the full suite → PASS.
• Step 5: Commit: feat(mudblazor): honor ShrinkLabel for collection item fields.

Task 5: Decide the LOV field's ShrinkLabel (flagged — behavior change)

Fields/LovField/MudBlazorLovFieldComponent.razor honors EffectiveVariant (line 17) but is the only variant-aware component that never sets ShrinkLabel, so it renders with MudBlazor's false while its 12 siblings pin the label. Adding ShrinkLabel="@EffectiveShrinkLabel" aligns it — and changes how LOV fields look today (label starts pinned instead of floating).

• Step 1: Confirm the asymmetry: grep -n 'ShrinkLabel\|EffectiveVariant' FormCraft.ForMudBlazor/Fields/LovField/MudBlazorLovFieldComponent.razor.
• Step 2: Take the call and record it in the PR description — recommended: align it (the input is ReadOnly="true" with a value-or-placeholder always shown, so a pinned label is the right rendering, and consistency across the field family is the point of this issue). If instead LOV is left alone, say so explicitly and add a code comment so the next reader doesn't "fix" it silently.
• Step 3: If aligning: write a failing test (LovField_Should_Honor_ShrinkLabel) asserting default true and .WithShrinkLabel(false) → false; run → FAIL.
• Step 4: If aligning: add ShrinkLabel="@EffectiveShrinkLabel" to the MudTextField at line 9-23; re-run → PASS; full suite → PASS.
• Step 5: Commit: fix(mudblazor): align LOV field ShrinkLabel with the other input components (or, if not aligning, docs(mudblazor): note why the LOV field leaves ShrinkLabel unset).

Task 6: Documentation

Files: modify README.md (the v3.1.0 feature bullet at line 65).

• Step 1: Add a feature bullet next to the existing Configurable MudBlazor Variant one, documenting .WithShrinkLabel(false) and DefaultShrinkLabel, and stating plainly that Variant.Text usually wants ShrinkLabel="false" so the label floats — with the two-line snippet.
• Step 2: Re-read the XML docs added in Tasks 1-2 and confirm each <example> compiles as written (correct namespaces, real member names).
• Step 3: Run the full solution build and test suite one final time: dotnet build then dotnet test → both green.
• Step 4: Commit: docs: document configurable ShrinkLabel and the Variant.Text pairing.