doc: Add a warning that destructing a Map by a key that doesn't exist…

… will throw a StateError (#6321)

Thanks for your contribution! Please replace this text with a
description of what this PR is changing or adding and why, list any
relevant issues, and review the contribution guidelines below.

Fixes #6320

---

- [X] I’ve reviewed the contributor guide and applied the relevant
portions to this PR.
- [X] This PR doesn't contain automatically generated corrections or
text (Grammarly, LLMs, and similar).
- [X] This PR follows the [Google Developer Documentation Style
Guidelines](https://developers.google.com/style) — for example, it
doesn't use _i.e._ or _e.g._, and it avoids _I_ and _we_ (first person).
- [X] This PR uses [semantic line
breaks](https://github.com/dart-lang/site-shared/blob/main/doc/writing-for-dart-and-flutter-websites.md#semantic-line-breaks)
of 80 characters or fewer.

<details>
  <summary>Contribution guidelines:</summary><br>

- See our [contributor
guide](https://github.com/dart-lang/site-www/blob/main/CONTRIBUTING.md)
for general expectations for PRs.
- Larger or significant changes should be discussed in an issue before
creating a PR.
- Code changes should generally follow the [Dart style
guide](https://dart.dev/effective-dart) and use `dart format`.
- Updates to [code
excerpts](https://github.com/dart-lang/site-shared/blob/main/packages/excerpter)
indicated by `<?code-excerpt` need to be updated in their source `.dart`
file as well.
</details>

---------

Co-authored-by: Marya Belanger <mbelanger@google.com>

examples/language/lib/patterns/pattern_types.dart

@@ -274,4 +274,10 @@ void miscDeclAnalyzedButNotTested() {
       _ => throw FormatException('Invalid')
     };
   }
+
+  {
+    // #docregion map-error
+    final {'foo': int? foo} = {};
+    // #enddocregion map-error
+  }
 }

src/content/language/pattern-types.md

@@ -362,6 +362,13 @@ match its subpatterns against the map's keys to destructure them.
 
 Map patterns don't require the pattern to match the entire map. A map pattern
 ignores any keys that the map contains that aren't matched by the pattern.
+Trying to match a key that does not exist in the map will
+throw a [`StateError`][]:
+
+<?code-excerpt "language/lib/patterns/pattern_types.dart (map-error)"?>
+```dart
+final {'foo': int? foo} = {};
+```
 
 ## Record
 
@@ -472,6 +479,7 @@ switch (record) {
 [Matching]: /language/patterns#matching
 [`List`]: /language/collections#lists
 [`Map`]: /language/collections#maps
+[`StateError`]: {{site.dart-api}}/dart-core/StateError-class.html
 [refuted]: /resources/glossary#refutable-pattern
 [record]: /language/records
 [shape]: /language/records#record-types