Add DropdownMenu.decorationBuilder

[bleroux]

Description

This PR adds DropdownMenu.decorationBuilder.
The goal is to make DropdownMenu more flexible.

Before this PR, several fields are used by DropdownMenu to create an inner InputDecoration. This approach has several limitations:

• InputDecoration has more fields that the ones that are exposed
• DropdownMenu makes some choices that can't be change. Especially, it creates an IconButton (with hardcoded padding) which is passed to InputDecoration.suffixIcon. This inner IconButton introduces some difficulty related to focus management and UI customization.

The new DropdownMenu.decorationBuilder property offers users a way to take control on the inner InputDecoration in a non-breaking way.

In a future PR, this property will help replacing the default IconButton.
Currently users can replace the IconButton using this code sample:

DropdownMenu without IconButton

import 'package:flutter/material.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  MyApp({super.key});

  final List<DropdownMenuEntry<String>> menuEntries = [
    "Red",
    "Green",
    "Blue",
  ].map((t) => DropdownMenuEntry<String>(label: t, value: t)).toList();

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        body: Center(
          child: SizedBox(
            width: 220,
            child: DropdownMenu<String>(
              expandedInsets: EdgeInsets.zero,
              requestFocusOnTap: true,
              dropdownMenuEntries: menuEntries,
              decorationBuilder: (context, controller) {
                return InputDecoration(
                  labelText: 'Label text',
                  helperText: 'Select a color or enter one',
                  suffixIcon: controller.isOpen
                      ? const Icon(Icons.arrow_drop_up)
                      : const Icon(Icons.arrow_drop_down),
                );
              },
            ),
          ),
        ),
      ),
    );
  }
}

Related Issue

Fixes DropDownMenu secondary trailing widget
Will help for Make DropdownMenu's trailing icon not focusable by default

Related discussions

#175847 (comment)
#175558 (comment)

Tests

• Adds 7 tests.

[gemini-code-assist]

Code Review

This pull request introduces DropdownMenu.decorationBuilder, a new property that provides a more flexible way to customize the InputDecoration of the DropdownMenu. This is a significant improvement over the previous method of exposing individual decoration properties. The implementation is robust, with assertions to prevent misuse and a clean refactoring that maintains backward compatibility. The accompanying tests are thorough. My review includes a couple of minor suggestions to fix typos in the documentation and a small correction in one of the new tests.

[QuncCccccc]

I like this approach! Thank you for the improvement. Overall this looks good to me:) Will take another look tomorrow.

[QuncCccccc]

Do you think if there will be a case where the user doesn't want the sufficIcon at all? I'm thinking whether we should still give it a default value when suffixIcon is null.

[bleroux]

Interesting.
The property DropdownMenu.showTrailingIcon was added some time ago in #167782 for that purpose.

Because DropdownMenu.decorationBuilder is new we can decide to use a different solution. Nonetheless, If we don't add a default suffix when suffixIcon is null, most of the users will have to provide their implementation or we have to offer them an API to get the default Icon. It seems to add complexity for a use case which is somewhat specific.

[Gustl22]

I'd propose to always add the default icon, also with a custom decoration (when the user adds an additinal trailing icon, then keep it in a Row). And the user can still disable it via the property showTrailingIcon. That way the dev does not need to implement it, e.g. also with providing more additional trailing actions, but still has the opportunity to remove it.
That way it has a purpose in all cases, while providing maximum flexibility and minimal effort for the dev.

The other way around: in the current implementation, if the user defines its own trailing icon, the showTrailingIcon does not have any effect, right?

[bleroux]

I'd propose to always add the default icon, also with a custom decoration (when the user adds an additinal trailing icon, then keep it in a Row)

Adding a Row fits specific use cases and for these use cases it might be better for us to expose the default button construction if you think this would be interesting and let users add a Row (or something else) if needed (that way they can control padding for instance or anything matching their design).
My reasonning is to remove as much as possible custom rendering logic outside of DropdownMenu. In that particular case, InputDecorator already implements APIs that comply with M3 spec (padding, defaults colors, borders, etc) and offer flexibility (InputDecoration.suffix, InputDecoration.suffixIcon, etc).

The other way around: in the current implementation, if the user defines its own trailing icon, the showTrailingIcon does not have any effect, right?

Yes. It surely should be documented (in fact the best move would probably to rename showTrailingIcon to showDefaultTrailingIcon in that case). We can also decide to ignore InputDecoration.suffixIcon if showTrailingIcon is false, it might be easier to document/understand.

[Gustl22]

Adding a Row fits specific use cases and for these use cases it might be better for us to expose the default button construction if you think this would be interesting and let users add a Row

Good point.
Of course the Row was just meant as an internal helper to still be able to access the default trailing icon. But yes, it would then only serve in that (in my opinion most common) use case, and shrinks flexibility how (e.g. in which order) to use it.

I personally don't need the default trailing button, as the fuctionality can easily be recreated with the controller. Not sure if folks would notice / search for the constructor of the default icon.

Yes. It surely should be documented (in fact the best move would probably to rename showTrailingIcon to showDefaultTrailingIcon in that case). We can also decide to ignore InputDecoration.suffixIcon if showTrailingIcon is false, it might be easier to document/understand.

Sounds reasonable. Happy with both variants :)

Btw thank you for your efforts!

[QuncCccccc]

when suffixIcon is null, most of the users will have to provide their implementation or we have to offer them an API to get the default Icon. It seems to add complexity for a use case which is somewhat specific.

I see, it makes sense to me.

[QuncCccccc]

LGTM. Thank you for adding all the tests:)