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

[Treamz]

TextField.decoration's dartdoc describes what the decoration draws, but never mentions that the value passed here is combined with the ambient InputDecorationTheme rather than replacing it.

TextField builds its effective decoration with InputDecoration.applyDefaults (packages/material_ui/lib/src/text_field.dart), and applyDefaults only substitutes properties that are null on the incoming InputDecoration — including border: border ?? theme.border (packages/material_ui/lib/src/input_decorator.dart). So a theme-provided border survives an InputDecoration that simply omits one, which is surprising if you read the property docs alone. That confusion is what flutter/flutter#159629 reports.

This adds a paragraph to the decoration property documenting the merge and pointing at the explicit opt-out (InputBorder.none).

This covers the documentation half of flutter/flutter#159629. The issue also proposes a mergeWithTheme-style flag on InputDecoration; that is an API proposal and is deliberately left out of this PR, so the issue should stay open.

Originally opened against flutter/flutter as flutter/flutter#191260, and moved here after the code-freeze bot pointed out that Material changes now belong in material_ui.

Documentation-only change; no behavior change and no new tests.

Pre-launch Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the Tree Hygiene page, which explains my responsibilities.
• I read and followed the relevant style guides and ran the auto-formatter.
• I signed the CLA.
• The title of the PR starts with the name of the package surrounded by square brackets, e.g. [shared_preferences]
• I listed at least one issue that this PR fixes in the description above.
• I updated pubspec.yaml with an appropriate new version according to the pub versioning philosophy, or this PR is exempt from version changes. — material_ui uses batch release (release: batch: true in ci_config.yaml), so this adds a pending_changelogs entry with version: patch rather than editing pubspec.yaml directly.
• I updated CHANGELOG.md to add a description of the change, following repository CHANGELOG style, or this PR is exempt from CHANGELOG changes. — same as above; CHANGELOG.md is generated at batch release time.
• I added new tests to check the change I am making, or this PR is test-exempt.
• All existing and new tests are passing.

[gemini-code-assist]

Code Review

This pull request updates the documentation for TextField.decoration to clarify that it merges with the ambient InputDecorationTheme rather than replacing it, alongside bumping the package version to 1.0.1. Feedback on the documentation changes suggests correcting a comma splice, clarifying the return type of InputDecorationTheme.of as InputDecorationThemeData, and using a proper Dartdoc reference for [InputBorder.none].

[gemini-code-assist]

There are a couple of areas for improvement in this documentation paragraph:\n\n1. Grammar: The first sentence contains a comma splice: ...ambient [InputDecorationTheme], it is merged.... It should be split into two sentences or separated with a semicolon.\n2. Accuracy: The phrase take their value from [InputDecorationTheme.of] is slightly imprecise because InputDecorationTheme.of is a static method that returns InputDecorationThemeData. It is clearer to state that they take their values from the InputDecorationThemeData returned by InputDecorationTheme.of.\n3. Dartdoc Reference: Instead of using backticks for border: InputBorder.none, we can use a proper Dartdoc reference [InputBorder.none] to make it clickable and consistent with other references in the paragraph.

  /// This decoration does not replace the ambient [InputDecorationTheme]. Instead,\n  /// it is merged with it by [InputDecoration.applyDefaults]. Only the properties\n  /// that are left null here take their value from the [InputDecorationThemeData]\n  /// returned by [InputDecorationTheme.of], which in turn defaults to\n  /// [ThemeData.inputDecorationTheme]. So, for example, when the theme specifies\n  /// a border, passing an [InputDecoration] that leaves [InputDecoration.border]\n  /// null does not remove that border; pass [InputBorder.none] to opt out of it\n  /// explicitly.

[flutter-dashboard]

It looks like this pull request may not have tests. Please make sure to add tests or get an explicit test exemption before merging.

If you are not sure if you need tests, consider this rule of thumb: the purpose of a test is to make sure someone doesn't accidentally revert the fix. Ask yourself, is there anything in your PR that you feel it is important we not accidentally revert back to how it was before your fix?

Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing. If you believe this PR qualifies for a test exemption, contact "@test-exemption-reviewer" in the #hackers channel in Discord (don't just cc them here, they won't see it!). The test exemption team is a small volunteer group, so all reviewers should feel empowered to ask for tests, without delegating that responsibility entirely to the test exemption group.