[material_ui] Document that TextField.decoration is merged with InputDecorationTheme

packages/material_ui/lib/src/text_field.dart

@@ -449,6 +449,15 @@ class TextField extends StatefulWidget {
   /// By default, draws a horizontal line under the text field but can be
   /// configured to show an icon, label, hint text, and error text.
   ///
+  /// This decoration does not replace the ambient [InputDecorationTheme].
+  /// Instead, it is merged with it by [InputDecoration.applyDefaults]. Only the
+  /// properties that are left null here take their value from the
+  /// [InputDecorationThemeData] returned by [InputDecorationTheme.of], which in
+  /// turn defaults to [ThemeData.inputDecorationTheme]. So, for example, when
+  /// the theme specifies a border, passing an [InputDecoration] that leaves
+  /// [InputDecoration.border] null does not remove that border; pass
+  /// [InputBorder.none] to opt out of it explicitly.
+  ///
   /// Specify null to remove the decoration entirely (including the
   /// extra padding introduced by the decoration to save space for the labels).
   final InputDecoration? decoration;

packages/material_ui/pending_changelogs/change_2026_08_18_text_field_decoration_docs.yaml

@@ -0,0 +1,4 @@
+changelog: |
+  - Documents that `TextField.decoration` is merged with the ambient
+    `InputDecorationTheme` rather than replacing it.
+version: patch