Add docs for null-aware element. (#6575)

This add the null-aware element to our [collections
documentation](https://dart.dev/language/collections).

Notes:
This is behind a beta feature flag right now.

Preview:

https://dart-dev--pr6575-null-aware-element-c-1p89rpex.web.app/language/collections#null-aware-element

Fixes [6458](#6458)

---

- [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.

---------

Co-authored-by: Parker Lougheed <parlough@gmail.com>

Author: antfitch

examples/misc/test/language_tour/collections/null_aware_element_a.dart

@@ -0,0 +1,20 @@
+// ignore_for_file: avoid_init_to_null, invalid_null_aware_operator
+
+import 'package:test/test.dart';
+
+void main() {
+  // #docregion code-sample
+  int? absentValue = null;
+  int? presentValue = 3;
+  var items = [
+    1,
+    ?absentValue,
+    ?presentValue,
+    absentValue,
+    5,
+  ]; // [1, 3, null, 5]
+  // #enddocregion code-sample
+
+  print(items);
+  expect(items, equals([1, 3, null, 5]));
+}

examples/misc/test/language_tour/collections/null_aware_element_b.dart

@@ -0,0 +1,35 @@
+// ignore_for_file: avoid_init_to_null
+
+import 'package:test/test.dart';
+
+void main() {
+  // #docregion code-sample
+  String? presentKey = 'Apple';
+  String? absentKey = null;
+
+  int? presentValue = 3;
+  int? absentValue = null;
+
+  var itemsA = {presentKey: absentValue}; // {Apple: null}
+  var itemsB = {presentKey: ?absentValue}; // {}
+
+  var itemsC = {absentKey: presentValue}; // {null: 3}
+  var itemsD = {?absentKey: presentValue}; // {}
+
+  var itemsE = {absentKey: absentValue}; // {null: null}
+  var itemsF = {?absentKey: ?absentValue}; // {}
+  // #enddocregion code-sample
+
+  print(itemsA);
+  print(itemsB);
+  print(itemsC);
+  print(itemsD);
+  print(itemsE);
+  print(itemsF);
+  expect(itemsA, equals({'Apple': null}));
+  expect(itemsB, equals({}));
+  expect(itemsC, equals({null: 3}));
+  expect(itemsD, equals({}));
+  expect(itemsE, equals({null: null}));
+  expect(itemsF, equals({}));
+}

src/content/language/collections.md

@@ -277,6 +277,10 @@ and control flow elements.
 *   Control flow element: Conditionally or iteratively adds
     zero or more values to the surrounding collection.
 
+    *   Null-aware element: Evaluates an expression and if
+        the result is not `null`, inserts the value into the
+        surrounding collection.
+
     *   Spread element: Iterates over a given sequence
         (collection expression) and inserts all of the
         resulting values into the surrounding collection.
@@ -328,6 +332,83 @@ A map entry element has this syntax in a collection:
 <key_expression>: <value_expression>
 ```
 
+### Null-aware elements {: #null-aware-element }
+
+A null-aware element evaluates an expression and if the
+result is not `null`, inserts the value into the surrounding
+collection.
+
+:::version-note
+Null-aware collection elements require
+a [language version][] of at least 3.8.
+:::
+
+A null-aware element has the following syntax in an
+expression element:
+
+```dart
+?<expression>
+```
+
+A null-aware element has the following syntax in a
+map entry element:
+
+```dart
+// key is a null-aware element
+?<key_expression>: <value_expression>
+```
+
+```dart
+// value is a null-aware element
+<key_expression>: ?<value_expression>
+```
+
+```dart
+// key and value are null-aware elements
+?<key_expression>: ?<value_expression>
+```
+
+In the following example, the result for the
+null-aware element `?a` is not added to a list called
+`items` because `a` is `null`:
+
+<?code-excerpt "misc/test/language_tour/collections/null_aware_element_a.dart (code-sample)"?>
+```dart
+int? absentValue = null;
+int? presentValue = 3;
+var items = [
+  1,
+  ?absentValue,
+  ?presentValue,
+  absentValue,
+  5,
+]; // [1, 3, null, 5]
+```
+
+The following example illustrates various ways that
+you can use null-aware elements inside of
+map entry elements:
+
+<?code-excerpt "misc/test/language_tour/collections/null_aware_element_b.dart (code-sample)"?>
+```dart
+String? presentKey = 'Apple';
+String? absentKey = null;
+
+int? presentValue = 3;
+int? absentValue = null;
+
+var itemsA = {presentKey: absentValue}; // {Apple: null}
+var itemsB = {presentKey: ?absentValue}; // {}
+
+var itemsC = {absentKey: presentValue}; // {null: 3}
+var itemsD = {?absentKey: presentValue}; // {}
+
+var itemsE = {absentKey: absentValue}; // {null: null}
+var itemsF = {?absentKey: ?absentValue}; // {}
+```
+
+[language version]: /resources/language/evolution#language-versioning
+
 ### Spread elements {: #spread-element }
 
 The spread element iterates over a given sequence and