Deprecate TextInputConnection.setStyle

src/content/release/breaking-changes/deprecate-text-input-connection-set-style.md

@@ -0,0 +1,75 @@
+title: Deprecate `TextInputConnection.setStyle`
+description: >-
+  The `TextInputConnection.setStyle` method has been deprecated in favor
+  of the `TextInputConnection.updateStyle` method.
+---
+
+{% render "docs/breaking-changes.md" %}
+
+## Summary
+
+`TextInputConnection.setStyle` is deprecated in favor of
+`TextInputConnection.updateStyle`, which supports synchronizing
+`letterSpacing`, `wordSpacing`, and `lineHeight` to the engine.
+
+## Context
+
+The previous `setStyle` method did not support `letterSpacing`, `wordSpacing`,
+or `lineHeight`. This caused visual misalignment of the selection highlight
+and IME caret when these properties were used.
+
+The replacement `updateStyle` method (via `TextInputStyle`) supports these
+properties, ensuring the system input is synchronized with the rendered text.
+
+## Migration guide
+
+Authors of custom text input clients should replace calls to
+`TextInputConnection.setStyle` with `TextInputConnection.updateStyle`.
+
+### Code before migration:
+
+```dart
+connection.setStyle(
+  fontFamily: 'Roboto',
+  fontSize: 14.0,
+  fontWeight: FontWeight.normal,
+  textDirection: TextDirection.ltr,
+  textAlign: TextAlign.start,
+);
+```
+
+### Code after migration:
+
+```dart
+connection.updateStyle(
+  TextInputStyle(
+    fontFamily: 'Roboto',
+    fontSize: 14.0,
+    fontWeight: FontWeight.normal,
+    textDirection: TextDirection.ltr,
+    textAlign: TextAlign.start,
+    letterSpacing: 1.2,
+    wordSpacing: 1.0,
+    lineHeight: 1.5,
+  ),
+);
+```
+
+## Timeline
+
+Landed in version: TBD<br>
+In stable release: Not yet
+
+## References
+
+Relevant PR:
+
+* [PR 180436][]
+
+Relevant issues:
+
+* [Issue 161592][]
+
+<!-- Stable channel link: -->
+[PR 180436]: {{site.repo.flutter}}/pull/180436
+[Issue 161592]: {{site.repo.flutter}}/issues/161592

src/content/release/breaking-changes/index.md

@@ -39,11 +39,13 @@ They're sorted by release and listed in alphabetical order:
 * [Migrating Flutter Android app to Android Gradle Plugin 9.0.0][]
 * [Deprecate `onReorder` callback][]
 * [Deprecated `cacheExtent` and `cacheExtentStyle`][]
+* [Deprecate `TextInputConnection.setStyle`][]
 * [Page transition builders reorganization][]
 
 [Migrating Flutter Android app to Android Gradle Plugin 9.0.0]: /release/breaking-changes/migrate-to-agp-9
 [Deprecate `onReorder` callback]: /release/breaking-changes/deprecate-onreorder-callback
 [Deprecated `cacheExtent` and `cacheExtentStyle`]: /release/breaking-changes/scroll-cache-extent
+[Deprecate `TextInputConnection.setStyle`]: /release/breaking-changes/deprecate-text-input-connection-set-style
 [Page transition builders reorganization]: /release/breaking-changes/decouple-page-transition-builders
 
 <a id="released-in-flutter-341" aria-hidden="true"></a>