Add breaking change "Material Chip button semantics" (#4312)

Author: nscobie

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

@@ -43,6 +43,7 @@ release, and listed in alphabetical order:
 * [The RenderEditable needs to be laid out before hit testing][]
 * [The Route Transition record and Transition delegate updates][]
 * [TestWidgetsFlutterBinding.clock][]
+* [Material Chip button semantics][]
 
 [Actions API revision]: /docs/release/breaking-changes/actions-api-revision
 [Adding 'linux' and 'windows' to TargetPlatform enum]: /docs/release/breaking-changes/target-platform-linux-windows
@@ -72,3 +73,4 @@ release, and listed in alphabetical order:
 [The Route and Navigator refactoring]: /docs/release/breaking-changes/route-navigator-refactoring
 [The Route Transition record and Transition delegate updates]: /docs/release/breaking-changes/route-transition-record-and-transition-delegate
 [ThemeData's accent properties]: /docs/release/breaking-changes/theme-data-accent-properties
+[Material Chip button semantics]: /docs/release/breaking-changes/material-chip-button-semantics

src/docs/release/breaking-changes/material-chip-button-semantics.md

@@ -0,0 +1,156 @@
+---
+title: Material Chip button semantics
+description: Interactive Material Chips are now semantically marked as buttons.
+---
+
+## Summary
+
+Flutter now applies the semantic label of `button` to all interactive [Material
+Chips][] for accessibility purposes.
+
+## Context
+
+Interactive Material Chips (namely [`ActionChip`][], [`ChoiceChip`][],
+[`FilterChip`][], and [`InputChip`][]) are now semantically marked as being
+buttons. However, the non-interactive information [`Chip`][] is not.
+
+Marking Chips as buttons helps accessibility tools, search engines, and other
+semantic analysis software understand the meaning of an app. For example, it
+allows screen readers (such as TalkBack on Android and VoiceOver on iOS) to
+announce a tappable Chip as a "button", which can assist users in navigating
+your app. Prior to this change, users of accessibility tools may have had a
+subpar experience, unless you implemented a workaround by manually adding the
+missing semantics to the Chip widgets in your app.
+
+## Description of change
+
+The outermost [`Semantics`][] widget that wraps all Chip classes to describe
+their semantic properties has been modified.
+
+For [`ActionChip`][], [`ChoiceChip`][], [`FilterChip`][], and [`InputChip`][]:
+
+- The [`button`][`SemanticsProperties.button`] property is set to `true`.
+- The [`enabled`][`SemanticsProperties.enabled`] property reflects whether the
+  Chip is _currently_ tappable (by having a callback set).
+
+These property changes bring interactive Chips' semantic behavior in-line with
+that of other [Material Buttons][].
+
+For the non-interactive information [`Chip`][]:
+
+- The [`button`][`SemanticsProperties.button`] property is set to `false`.
+- The [`enabled`][`SemanticsProperties.enabled`] property is set to `null`.
+
+## Migration guide
+
+**You might not need to perform any migration.** This change only affects you if
+you worked around the issue of Material Chips missing `button` semantics by
+wrapping the widget given to the `label` field of a `Chip` with a `Semantics`
+widget marked as `button: true`. **In this case, the inner and outer `button`
+semantics conflict, resulting in the tappable area of the button shrinking
+down to the size of the label after this change is introduced.** Fix this issue
+either by deleting that `Semantics` widget and replacing it with its child,
+or by removing the `button: true` property if other semantic properties still
+need to be applied to the `label` widget of the Chip.
+
+The following snippets use [`InputChip`][] as an example, but the same process
+applies to [`ActionChip`][], [`ChoiceChip`][], and [`FilterChip`][] as well.
+
+**Case 1: remove the `Semantics` widget.**
+
+Code before migration:
+
+<!-- skip -->
+```dart
+Widget myInputChip = InputChip(
+  onPressed: () {},
+  label: Semantics(
+    button: true,
+    child: Text('My Input Chip'),
+  ),
+);
+```
+
+Code after migration:
+
+<!-- skip -->
+```dart
+Widget myInputChip = InputChip(
+  onPressed: () {},
+  label: Text('My Input Chip'),
+);
+```
+
+**Case 2: remove `button:true` from the `Semantics` widget.**
+
+Code before migration:
+
+<!-- skip -->
+```dart
+Widget myInputChip = InputChip(
+  onPressed: () {},
+  label: Semantics(
+    button: true,
+    hint: 'Example Hint',
+    child: Text('My Input Chip'),
+  ),
+);
+```
+
+Code after migration:
+
+<!-- skip -->
+```dart
+Widget myInputChip = InputChip(
+  onPressed: () {},
+  label: Semantics(
+    hint: 'Example Hint',
+    child: Text('My Input Chip'),
+  ),
+);
+```
+
+## Timeline
+
+Landed in version: TBD<br> In stable release: not yet
+
+## References
+
+{% include master-api.md %}
+
+API documentation:
+* [`ActionChip`][]
+* [`Chip`][]
+* [`ChoiceChip`][]
+* [`FilterChip`][]
+* [`InputChip`][]
+* [Material Buttons][]
+* [Material Chips][]
+* [`Semantics`][]
+* [`SemanticsProperties.button`][]
+* [`SemanticsProperties.enabled`][]
+
+Relevant issues:
+* [flutter/flutter#58010][]
+
+Relevant PRs:
+* [Tweaking Material Chip a11y semantics to match buttons][]
+* [Revert "Tweaking Material Chip a11y semantics to match buttons (#60141)"][]
+* [Re-land "Tweaking Material Chip a11y semantics to match buttons (#60141)"][]
+
+[`ActionChip`]: {{site.api}}/flutter/material/ActionChip-class.html
+[`Chip`]: {{site.api}}/flutter/material/Chip-class.html
+[`ChoiceChip`]: {{site.api}}/flutter/material/ChoiceChip-class.html
+[`FilterChip`]: {{site.api}}/flutter/material/FilterChip-class.html
+[`InputChip`]: {{site.api}}/flutter/material/InputChip-class.html
+[Material Buttons]: {{site.material}}/components/buttons
+[Material Chips]: {{site.material}}/components/chips
+[`Semantics`]: {{site.api}}/flutter/widgets/Semantics-class.html
+[`SemanticsProperties.button`]: {{site.api}}/flutter/semantics/SemanticsProperties/button.html
+[`SemanticsProperties.enabled`]: {{site.api}}/flutter/semantics/SemanticsProperties/enabled.html
+
+[flutter/flutter#58010]: {{site.github}}/flutter/flutter/issues/58010
+
+[Tweaking Material Chip a11y semantics to match buttons]: {{site.github}}/flutter/flutter/pull/60141
+[Revert "Tweaking Material Chip a11y semantics to match buttons (#60141)"]: {{site.github}}/flutter/flutter/pull/60645
+[Re-land "Tweaking Material Chip a11y semantics to match buttons (#60141)"]: {{site.github}}/flutter/flutter/pull/61048