- {{ content }}
-
-
- {{ content }}
-
- ```
- ```ts
- // inside of your component
- \@ViewChild(LetDirective) rxLet: LetDirective{{ content }}
+{{ content }}
+{{ content }}
+```
+
+```ts
+// inside of your component
+\@ViewChild(LetDirective) rxLet: LetDirectiveCount: {{ count }}
-- Error! -
+Error!
-- Complete! -
+Complete!
-- Loading... -
+Loading...
+
Count: {{ count }}
-
+
```
### `set primaryStrategy()`
@@ -143,7 +144,7 @@ const primaryStrategy$ = this.strategyProvider.primaryStrategy$;
```
```html
-
+
```
### `strategies$`
@@ -158,7 +159,7 @@ const strategyNames$ = this.strategyProvider.strategyNames$;
### `schedule` & `scheduleWith`
-These methods allows users to schedule any kind of work.
+These methods allows users to schedule any kind of work.
- `schedule` returns an observable (don't forget to subscribe!)
- `scheduleWith` returns a `MonoTypeOperatorFunction` so you can use this method inside rxjs `pipe`
@@ -176,16 +177,19 @@ Options are configuration object that you can use to setup the scheduling behavi
#### Usage examples
```typescript
-this.strategyProvider.schedule(() =>
- myWork(),
- {strategy: 'idle', patchZone: false, scope: this}
-).subscribe();
-
-myObservable$.pipe(
- this.strategyProvider.scheduleWith(
- () => myWork(),
- {strategy: 'idle', patchZone: false, scope: this})
-).subscribe();
+this.strategyProvider
+ .schedule(() => myWork(), { strategy: 'idle', patchZone: false, scope: this })
+ .subscribe();
+
+myObservable$
+ .pipe(
+ this.strategyProvider.scheduleWith(() => myWork(), {
+ strategy: 'idle',
+ patchZone: false,
+ scope: this,
+ })
+ )
+ .subscribe();
```
### `scheduleCD` method
@@ -198,10 +202,11 @@ Imperative method that you can use to schedule change detection cycle. You must
#### Usage example
```typescript
-this.strategyProvider.scheduleCd(this.changeDetectorRef, {afterCD: myWork()});
+this.strategyProvider.scheduleCd(this.changeDetectorRef, { afterCD: myWork() });
```
## Links
+
- [Demo](https://stackblitz.com/edit/angular-ivy-1vfpoe)
-- [Detailed information about strategies](https://github.com/rx-angular/rx-angular/tree/master/libs/cdk/render-strategies)
+- [Detailed information about strategies](render-strategies.mdx)
- [MessageChannel documentation](https://developer.mozilla.org/en-US/docs/Web/API/MessageChannel)
diff --git a/libs/cdk/render-strategies/docs/basic-strategies.md b/apps/docs/docs/cdk/render-strategies/strategies/basic-strategies.md
similarity index 86%
rename from libs/cdk/render-strategies/docs/basic-strategies.md
rename to apps/docs/docs/cdk/render-strategies/strategies/basic-strategies.md
index 0111bd27a8..3d14ed5db6 100644
--- a/libs/cdk/render-strategies/docs/basic-strategies.md
+++ b/apps/docs/docs/cdk/render-strategies/strategies/basic-strategies.md
@@ -1,4 +1,4 @@
-# Basic Strategies
+# Basic strategies
## Concepts
@@ -8,6 +8,7 @@ To apply changes to a component template we need to re-evaluate the template. In
This process will execute whenever a component's template is re-evaluated through `async`, `push`, `ChangedDetectorRef.detectChanges` or a structural directive template is re-evaluated through `EmbeddedView.detectChanges`.
It can be pretty time consuming and directly depends on the following factors:
+
- HTML size (only for init and destroy and bundle-size)
- JS size (only for init and destroy and bundle-size)
- number of event bindings (only for init and destroy)
@@ -20,27 +21,29 @@ Some of the problems related to work of Angular are:
**Out of bound change detection:**
If we perform this re-evaluation without any visual change for the user (over-rendering) we introduce noticeable performance degradations.
-The out of bound change detection can be caused through:
- - Zone pollution
- - Missing ChangeDetectionStrategy.OnPush
- - Component template projection
- - Pull-based rendering processes
-
+The out of bound change detection can be caused through:
+
+- Zone pollution
+- Missing ChangeDetectionStrategy.OnPush
+- Component template projection
+- Pull-based rendering processes
+
**Out of bound template evaluation:**
-If we perform a re-evaluation of a single property in the template any other expression/binding also gets re-evaluated.
+If we perform a re-evaluation of a single property in the template any other expression/binding also gets re-evaluated.
Again over-rendering introduces noticeable performance degradations.
The out of bound template evaluation can be caused through:
- - Pull-based rendering processes
- - any reactive change through `async`
- - any call to `cdRef.detectChanges`
+- Pull-based rendering processes
+- any reactive change through `async`
+- any call to `cdRef.detectChanges`
**Work performed for out of viewport content:**
If we perform a re-evaluation or even re-rendering of the DOM of elements outside of the viewport we perform useless work for the user.
This will pollute the main thread and reduced time for more important content to get rendered.
The re-evaluation or browser re-rendering can be caused by:
+
- Bad style changes
- Big LCP (Largest Contentful Paint) elements
- Large amount of content
@@ -50,7 +53,7 @@ The re-evaluation or browser re-rendering can be caused by:
The change detection system that is currently implemented in Angular is pull-based, but way more important, as a side effect it also runs CD globally.
-It performs a re-rendering where at optimum every single component on the path from the root to the actual UI update needs to get re-evaluated.
+It performs a re-rendering where at optimum every single component on the path from the root to the actual UI update needs to get re-evaluated.
A lot of performed work is useless.
Technically the methods to run change detection are `markForCheck` / `markViewDirty`, `ɵmarkDirty` and `tick`.
@@ -61,32 +64,30 @@ Technically the methods we can use for it are `detectChanges` or `ɵdetectChange
-
### Pull vs push based
-
Consuming value changes can be done by **constantly** watching the source for changes and **pull** them,
- or subscribe to the changes like a DOM event binding **once** and get the changes **pushed**.
+or subscribe to the changes like a DOM event binding **once** and get the changes **pushed**.
In a simple setup the pull might be a quick solution and you just `.get()` the value, but a push based architecture always scales better.
Compare it with HTTP calls vs WebSockets.
-If we apply this concepts to our change detection mechanics we can directly apply changes where they are needd and skip nearly all the unnessecary work.
+If we apply this concepts to our change detection mechanics we can directly apply changes where they are needd and skip nearly all the unnessecary work.
In combination with Observables, and EmbeddedViews change detection can be speed up dramatically by this architecture.
-
+
### Strategies
-| Name | Priority | Render Method | Scheduling | Render Deadline |
-|-------------------------| -------- | ----------------- | ----------------------- | --------------- |
-| `"native"` | ❌ | ⮁ `markForCheck` | `requestAnimationFrame` | N/A |
+| Name | Priority | Render Method | Scheduling | Render Deadline |
+| ------------------------- | -------- | ----------------- | ----------------------- | --------------- |
+| `"native"` | ❌ | ⮁ `markForCheck` | `requestAnimationFrame` | N/A |
| `"global"` - _deprecated_ | ❌ | ⮁ `ɵmarkDirty` | `requestAnimationFrame` | N/A |
-| `"local"` | ❌ | 🠗 `detectChanges` | `requestAnimationFrame` | N/A |
-| `"noop"` | ❌ | - `noop` | `requestAnimationFrame` | N/A |
+| `"local"` | ❌ | 🠗 `detectChanges` | `requestAnimationFrame` | N/A |
+| `"noop"` | ❌ | - `noop` | `requestAnimationFrame` | N/A |
#### Native
@@ -103,7 +104,7 @@ as the internally called function [`markViewDirty`](https://github.com/angular/a
#### Global Strategy
-> **deprecated**
+> **deprecated**
> angular [drops support](https://github.com/angular/angular/pull/46806) for `ɵmarkDirty`
This strategy leverages Angular's internal [`ɵmarkDirty`](https://github.com/angular/angular/blob/930eeaf177a4c277f437f42314605ff8dc56fc82/packages/core/src/render3/instructions/change_detection.ts#L36) render method.
@@ -155,41 +156,32 @@ The no-operation strategy does nothing. It can be a valuable tool for performanc
| ------ | ------------- | ------------- | ---------- | ---------- |
| `noop` | ✔ | - `noop` | ❌ | ❌ |
-
## Usage
### Component / Service
```ts
-import {RxStrategyProvider} from '@rx-angular/cdk/render-strategies';
+import { RxStrategyProvider } from '@rx-angular/cdk/render-strategies';
@Component()
class Component {
-
constructor(private strategyProvider: RxStrategyProvider) {
- strategyProvider.schedule(() => {}, {strategyName: 'local'})
+ strategyProvider.schedule(() => {}, { strategyName: 'local' });
}
-
}
```
### Template
```ts
-import {LetModule} from '@rx-angular/template/let';
-import {ForModule} from '@rx-angular/template/for';
-import {PushModule} from '@rx-angular/template/push';
+import { LetModule } from '@rx-angular/template/let';
+import { ForModule } from '@rx-angular/template/for';
+import { PushModule } from '@rx-angular/template/push';
@Module({
- imports: [
- LetModule,
- ForModule,
- PushModule
- ]
+ imports: [LetModule, ForModule, PushModule],
})
-class Module {
-
-}
+class Module {}
```
```html
diff --git a/libs/cdk/render-strategies/docs/concurrent-strategies.md b/apps/docs/docs/cdk/render-strategies/strategies/concurrent-strategies.md
similarity index 90%
rename from libs/cdk/render-strategies/docs/concurrent-strategies.md
rename to apps/docs/docs/cdk/render-strategies/strategies/concurrent-strategies.md
index 10e818dcbf..297fdacc44 100644
--- a/libs/cdk/render-strategies/docs/concurrent-strategies.md
+++ b/apps/docs/docs/cdk/render-strategies/strategies/concurrent-strategies.md
@@ -1,17 +1,19 @@
-# Concurrent Strategies
+# Concurrent strategies
Based on the [RAIL model](https://web.dev/rail/), e.g. if your app provides animated user feedback within more than 16ms (less than 60 frames per second), it feels laggy to the user and leads to bad UX.
From the UX perspective that means users should not experience blocking periods more than 16 ms.
## Concepts
+
There are 5 core concepts of the concurrent strategies:
+
- Frame budget / Frame drop
- Scheduling
- Priority
- Chunking
- Concurrent Scheduling
-### Frame budget / Frame Drop
+### Frame budget / Frame drop
The Browser has only one UI thread (main thread), meaning things happen one after another.
@@ -48,11 +50,12 @@ When it comes to scripting work we can do 2 things to avoid that:
- reduce scripting work and let the user interact earlier
- chunk up work and use scheduling API's to distribute the work overtime and let the user interact in between.
-It is often the case that the work just can't get reduced so we have to schedule.
+It is often the case that the work just can't get reduced so we have to schedule.
Some of the possible APIs are:
+
- queueMicrotask
- setTimeout
- postMessage
@@ -70,7 +73,7 @@ A simple way to schedule work is using `setTimeout`.
```typescript
function work(): viod {
- concole.log('work done!');
+ concole.log('work done!');
}
const asyncId = setTimeout(work);
@@ -84,11 +87,10 @@ This is important for cancellation and cleanup logic.
```typescript
clearTimeout(asyncId);
-```
+```
If we pass the asyncId as parameter to the `clearTimeout` function we can cancel the scheduling and `work` will never get executed.
-
### Priority
@@ -102,7 +104,7 @@ Input handlers (tap, click etc.) often need to schedule a combination of differe
To get the best user experience we should prioritize this tasks.
-There are couple of scheduling APIs mentioned under scheduling.
+There are couple of scheduling APIs mentioned under scheduling.
They all help to prioritize the work and define the moment of execution differently.
@@ -127,14 +129,15 @@ This scenario gets to a problem depending on:
- the number of Angular elements
- the amount of work done in the elements
-### Concurrent Scheduling
+### Concurrent scheduling
Concurrent scheduling is a marketing term and simply means that there is a mechanism in place that knows how much time is spent in the current task.
-This number is called frame budget and measured in milliseconds. As a result of this technique we're getting prioritized user-centric scheduling behaviours.
+This number is called frame budget and measured in milliseconds. As a result of this technique we're getting prioritized user-centric scheduling behaviours.
This enables:
+
- scheduling
- cancellation
- fine grained prioritization
@@ -142,14 +145,14 @@ This enables:
- render deadlines
One of the first things to understand is the term "frame budget".
-It means we have a maximum time (which is globally defined) a task can take before yielding to the main thread. e.g. 60frames/1000ms=16.6666ms animations or 50ms long task.
+It means we have a maximum time (which is globally defined) a task can take before yielding to the main thread. e.g. 60frames/1000ms=16.6666ms animations or 50ms long task.
Scheduling with notion of frame budget enables us to split work into individual browser tasks as soon as we exceed the budget.
-We then yield to the main thread and are interactive again until the next batch of tasks will get processed.
+We then yield to the main thread and are interactive again until the next batch of tasks will get processed.
-The special thing about the set of concurrent strategies is they have a render deadline.
+The special thing about the set of concurrent strategies is they have a render deadline.
It means if the scheduled tasks in the global queue of work is not exhausted after a certain time window, we stop the chunking process.
Instead all remaining work will get executed as fast as possible. This means in one synchronous block (that potentially can causes a frame drop).
@@ -196,10 +199,10 @@ Tooltips should be displayed immediately on mouse over. Any delay will be very n
@Component({
selector: 'item-image',
template: `
- ![]()
`,
})
@@ -209,21 +212,25 @@ export class ItemsListComponent {
constructor(private strategyProvider: RxStrategyProvider) {}
showTooltip() {
- this.strategyProvider.schedule(
- () => {
- // create tooltip
- },
- { strategy: 'immediate' }
- ).subscribe();
+ this.strategyProvider
+ .schedule(
+ () => {
+ // create tooltip
+ },
+ { strategy: 'immediate' }
+ )
+ .subscribe();
}
hideTooltip() {
- this.strategyProvider.schedule(
- () => {
- // destroy tooltip
- },
- { strategy: 'immediate' }
- ).subscribe();
+ this.strategyProvider
+ .schedule(
+ () => {
+ // destroy tooltip
+ },
+ { strategy: 'immediate' }
+ )
+ .subscribe();
}
}
```
@@ -231,7 +238,7 @@ export class ItemsListComponent {
> **⚠ Notice:**
> Be aware to avoid scheduling large or non-urgent work with immediate priority as it blocks rendering
-### User Blocking
+### User blocking
@@ -279,17 +286,19 @@ export class DropdownComponent {
}
hideDropdown() {
- this.strategyProvider.schedule(
- () => {
- // destroy dropdown
- },
- { strategy: 'userBlocking' }
- ).subscribe();
+ this.strategyProvider
+ .schedule(
+ () => {
+ // destroy dropdown
+ },
+ { strategy: 'userBlocking' }
+ )
+ .subscribe();
}
}
```
-> **⚠ Notice:**
+> **⚠ Notice:**
> Be aware to avoid scheduling large or non-urgent work with `userBlocking` priority as it blocks rendering after 250ms
### Normal
@@ -310,7 +319,7 @@ Heavy work visible to the user. For example, since it has a higher timeout, it i
-For `normal` strategy a perfect example will be rendering of the items list.
+For `normal` strategy a perfect example will be rendering of the items list.
It is often the case that rendering of big lists blocks user interactions. In combination with `rxFor` directive such operations become truly unblocking.
@@ -373,22 +382,26 @@ export class ItemsListComponent {
) {}
openCreateItemPopup() {
- this.strategyProvider.schedule(() => {
- // logic to lazy load popup component
- }, {strategy: 'low'}).subscribe();
+ this.strategyProvider
+ .schedule(
+ () => {
+ // logic to lazy load popup component
+ },
+ { strategy: 'low' }
+ )
+ .subscribe();
}
-
}
```
-> **⚠ Notice:**
+> **⚠ Notice:**
> This priority fits well for things that should happen but has lower priority. For any non-urgent background process `idle` is the best fit.
### Idle
-Urgent work that should happen in the background and is not initiated but visible by the user. This occurs right after current task and has the lowest priority.
+Urgent work that should happen in the background and is not initiated but visible by the user. This occurs right after current task and has the lowest priority.
| Render Method | Scheduling | Render Deadline |
| ----------------- | ------------- | --------------- |
@@ -425,22 +438,28 @@ export class ItemsListComponent {
private strategyProvider: RxStrategyProvider,
private webSocket: WebSocketService
) {
- this.items$.pipe(
- this.strategyProvider.scheduleWith(
- items => this.webSocket.syncItems(items),
- {strategy: 'idle'}
- )
- ).subscribe();
+ this.items$
+ .pipe(
+ this.strategyProvider.scheduleWith(
+ (items) => this.webSocket.syncItems(items),
+ { strategy: 'idle' }
+ )
+ )
+ .subscribe();
}
openCreateItemPopup() {
- this.strategyProvider.schedule(() => {
- // logic to lazy load popup component
- }, {strategy: 'low'}).subscribe();
+ this.strategyProvider
+ .schedule(
+ () => {
+ // logic to lazy load popup component
+ },
+ { strategy: 'low' }
+ )
+ .subscribe();
}
-
}
```
-> **⚠ Notice:**
+> **⚠ Notice:**
> This priority fits well for low priority background processes that are not affecting user interactions.
diff --git a/libs/cdk/render-strategies/docs/strategies.md b/apps/docs/docs/cdk/render-strategies/strategies/strategies.mdx
similarity index 91%
rename from libs/cdk/render-strategies/docs/strategies.md
rename to apps/docs/docs/cdk/render-strategies/strategies/strategies.mdx
index fd9ff95123..718530bf18 100644
--- a/libs/cdk/render-strategies/docs/strategies.md
+++ b/apps/docs/docs/cdk/render-strategies/strategies/strategies.mdx
@@ -1,3 +1,9 @@
+---
+sidebar_label: 'Strategies'
+sidebar_position: 1
+hide_title: true
+---
+
# Strategies
Before we go into detail with the provided strategies, let's understand angulars vanilla behaviour first.
@@ -19,13 +25,15 @@ In many cases, this leads to heavy refactorings to get the performance flaw out
Strategies give us a way to control how Angular's rendering is executed and which render method is used.
-**Strategy Sets:**
-- [Basic Strategies](https://github.com/rx-angular/rx-angular/blob/master/libs/cdk/render-strategies/docs/basic-strategies.md)
-- [Concurrent Strategies](https://github.com/rx-angular/rx-angular/blob/master/libs/cdk/render-strategies/docs/concurrent-strategies.md)
+**Strategy sets:**
+
+- [Basic strategies](basic-strategies.md)
+- [Concurrent strategies](concurrent-strategies.md)
## Usage
### Configure existing features
+
```typescript
@Component({
selector: 'immediate',
@@ -58,8 +66,7 @@ export class RenderCallbackComponent {
}
```
-
-### Custom Strategies
+### Custom strategies
```typescript
export type RxRenderWork = (
diff --git a/apps/docs/docs/cdk/template-management/template-management.mdx b/apps/docs/docs/cdk/template-management/template-management.mdx
new file mode 100644
index 0000000000..162133509f
--- /dev/null
+++ b/apps/docs/docs/cdk/template-management/template-management.mdx
@@ -0,0 +1,17 @@
+---
+sidebar_label: 'Template management'
+sidebar_position: 1
+title: 'Template management'
+hide_title: true
+---
+
+import Readme, {
+ toc as readmeToc,
+} from '@site/../../libs/cdk/template/README.md';
+
+
-
-