docs: control flow API reference (angular#52397)

Adds API reference for the new built-in control flow.

PR Close angular#52397

Author: pkozlowski-opensource

aio/content/blocks/core/for.md

@@ -1 +1,46 @@
-Placeholder content
+The `@for` block repeatedly renders content of a block for each item in a collection.
+
+@syntax
+
+```html
+@for (item of items; track item.name) {
+  <li> {{ item.name }} </li>
+} @empty {
+  <li> There are no items. </li>
+}
+```
+
+@description
+
+The `@for` block renders its content in response to changes in a collection. Collections can be any JavaScript [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols), but there are performance advantages of using a regular `Array`.
+
+You can optionally include an `@empty` section immediately after the `@for` block content. The content of the `@empty` block displays when there are no items.
+
+<h3> track and objects identity </h3>
+
+The value of the `track` expression determines a key used to associate array items with the views in the DOM. Having clear indication of the item identity allows Angular to execute a minimal set of DOM operations as items are added, removed or moved in a collection. 
+
+Loops over immutable data without `trackBy` as one of the most common causes for performance issues across Angular applications. Because of the potential for poor performance, the `track` expression is required for the `@for` loops. When in doubt, using `track $index` is a good default.
+
+<h3> `$index` and other contextual variables </h3>
+
+Inside `@for`  contents, several implicit variables are always available:
+
+| Variable | Meaning |
+| -------- | ------- |
+| `$count` | Number of items in a collection iterated over |
+| `$index` | Index of the current row |
+| `$first` | Whether the current row is the first row |
+| `$last` | Whether the current row is the last row |
+| `$even` | Whether the current row index is even |
+| `$odd` | Whether the current row index is odd |
+
+These variables are always available with these names, but can be aliased via a `let` segment:
+
+```html
+@for (item of items; track item.id; let idx = $index, e = $even) {
+  Item #{{ idx }}: {{ item.name }}
+}
+```
+
+The aliasing is especially useful in case of using nested `@for` blocks where contextual variable names could collide.

aio/content/blocks/core/if.md

@@ -1,12 +1,25 @@
-Control flow block used to conditionally render content in the DOM.
+The `@if` block conditionally displays its content when its condition expression is truthy. 
 
 @syntax
 
 ```html
-@if ( <condition> ) {
-  <!-- conditional template fragment -->
+@if (a > b) {
+  {{a}} is greater than {{b}}
+} @else if (b > a) {
+  {{a}} is less than {{b}}
+} @else {
+  {{a}} is equal to {{b}}
 }
 ```
 
 @description
-This is the full description.
+
+Content is added and removed from the DOM based on the evaluation of conditional expressions in the `@if` and `@else` blocks.
+
+The built-in `@if` supports referencing of expression results to keep a solution for common coding patterns:
+
+```html
+@if (users$ | async; as users) {
+  {{ users.length }}
+}
+```

aio/content/blocks/core/switch.md

@@ -1 +1,25 @@
-Placeholder content
+The `@switch` block is inspired by the JavaScript `switch` statement:
+
+@syntax
+
+```html
+@switch (condition) {
+  @case (caseA) {
+    Case A.
+  }
+  @case (caseB) {
+    Case B.
+  }
+  @default {
+    Default case.
+  }
+}
+```
+
+@description
+
+The `@switch` blocks displays content selected by one of the cases matching against the conditional expression. The value of the conditional expression is compared to the case expression using the `===` operator.
+
+The `@default` block is optional and can be omitted. If no `@case` matches the expression and there is no `@default` block, nothing is shown.
+
+**`@switch` does not have fallthrough**, so you do not need an equivalent to a `break` or `return` statement.