Skip to content

Commit 3073289

Browse files
hakimiohakimio
committed
docs: migration guide
1 parent 940a3f4 commit 3073289

File tree

5 files changed

+230
-17
lines changed

5 files changed

+230
-17
lines changed

‎README.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,19 @@ found in the Angular.
1010

1111
---
1212

13+
### Migration to v19
14+
15+
Check out the [migration guide](docs/introduction/migration-v19.md) when migrating to `v19` from `v18` or earlier.
16+
17+
### Compatiblity
18+
19+
| Angular | cdk / ngxs | Standalone Components |
20+
| ------- | ---------- | --------------------- |
21+
| 20+ | 19 | ✔️ |
22+
| 18+ | 18 | ❌ |
23+
24+
### Packages
25+
1326
| **Package** | **Version** | **README** | **Downloads** |
1427
| -------------------------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
1528
| [@angular-ru/cdk](https://npmjs.com/package/@angular-ru/cdk) | ![](https://img.shields.io/npm/v/%40angular-ru%2Fcdk/latest.svg) | [![](https://img.shields.io/badge/Documentation--green.svg)](https://angular-ru.gitbook.io/sdk/cdk) | [![](https://img.shields.io/npm/dw/@angular-ru/cdk)](https://npmjs.com/package/@angular-ru/cdk) |

‎docs/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
- Getting Started
44
- [Introduction](introduction/intro.md)
5+
- [Migration Guide](introduction/migration-v19.md)
56
- CDK
67
- [@angular-ru/cdk/typings](cdk/typings.md)
78
- [@angular-ru/cdk/number](cdk/number.md)

‎docs/introduction/migration-v19.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
## `v19` Migration Guide
2+
3+
`v19` of `@angular-ru/cdk` and `@angular-ru/ngxs` has been updated to utilize the latest features from Angular `v20`.
4+
This includes standalone components, environment providers, component input signals, and more. Because of this,
5+
migration is slightly more involved than usual.
6+
7+
### Standalone components, directives, and pipes
8+
9+
All `NgModules` have been removed. Components, directives, and pipes have been made standalone and some of the suffixes
10+
(Directive, Component) have been dropped.
11+
12+
Here is an example of code before and after the migration:
13+
14+
**Before:**
15+
16+
```ts
17+
import {DisableControlDirectiveModule, AmountFormatModule, InputFilterModule} from '@angular-ru/cdk/directives';
18+
import {MutableTypePipeModule, DeepPathPipeModule} from '@angular-ru/cdk/pipes';
19+
20+
@Component({
21+
//...
22+
imports: [
23+
DisableControlDirectiveModule,
24+
AmountFormatModule,
25+
InputFilterModule,
26+
MutableTypePipeModule,
27+
DeepPathPipeModule,
28+
],
29+
})
30+
export class MyComponent {}
31+
```
32+
33+
**After:**
34+
35+
```ts
36+
import {DisableControl, AmountFormat, InputFilter} from '@angular-ru/cdk/directives';
37+
import {MutableTypePipe, DeepPathPipe} from '@angular-ru/cdk/pipes';
38+
39+
@Component({
40+
//...
41+
imports: [DisableControl, AmountFormat, InputFilter, MutableTypePipe, DeepPathPipe],
42+
})
43+
export class MyComponent {}
44+
```
45+
46+
### `FeatureModule.forRoot()` module providers have been replaced with `provideFeature()` environment providers
47+
48+
| **Module provider** | **Environment provider** |
49+
| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
50+
| `InputFilterModule.forRoot()` | `provideInputFilter()` |
51+
| `AmountFormatModule.forRoot()` | `provideAmountFormat()` |
52+
| `DataHttpClientModule.forRoot()` | `provideDataHttpClientOptions()` |
53+
| `DataHttpClientModule.forFeature()` | `provideDataHttpClientClients()` |
54+
| `ExcelBuilderModule.forRoot()` | `provideExcelBuilder()` |
55+
| `EXCEL_BUILDER_NGX_TRANSLATE_FALLBACK_PROVIDER` | `provideExcelBuilderNgxTranslateFallback()` |
56+
| `LoggerModule.forRoot()` | `provideLogger()` |
57+
| `NgxsDataPluginModule.forRoot()` | `provideNgxsDataPlugin()` |
58+
| `NgxsDataPluginModule.forRoot([NGXS_DATA_STORAGE_EXTENSION, NGXS_DATA_STORAGE_CONTAINER]),` | `provideNgxsDataPlugin(withNgxsDataStorage())` |
59+
| `NgxsDataPluginModule.forRoot([MY_FIRST_EXTENSION, MY_SECOND_EXTENSION])` | `provideNgxsDataPlugin(MY_FIRST_EXTENSION, MY_SECOND_EXTENSION)` |
60+
| `TooltipModule.forRoot()` | `provideTooltip()` |
61+
| `TableBuilderModule.forRoot()` | `provideVirtualTable()` |
62+
| `DateSuggestionModule.forRoot()` | `provideDateSuggestion()` |
63+
| `PlainTableComposerModule.forRoot()` | `providePlainTableComposer()` |
64+
| `TableClipboardModule` | `provideTableClipboard()` |
65+
| `WebsocketModule.forRoot()` | `provideWebsocket()` |
66+
67+
**Before:**
68+
69+
```ts
70+
export const appConfig: ApplicationConfig = {
71+
providers: [importProvidersFrom(NgxsDataPluginModule.forRoot())],
72+
};
73+
```
74+
75+
**After:**
76+
77+
```ts
78+
export const appConfig: ApplicationConfig = {
79+
providers: [provideNgxsDataPlugin()],
80+
};
81+
```
82+
83+
### NGXS Data Plugin Extensions
84+
85+
All ngxs data plugin extensions now have to be environment providers.
86+
87+
**Before:**
88+
89+
```ts
90+
import {NgxsDataExtension} from '@angular-ru/ngxs/typings';
91+
92+
export const MY_FIRST_EXTENSION: NgxsDataExtension = {
93+
provide: NGXS_PLUGINS,
94+
useClass: MySuperService,
95+
multi: true,
96+
};
97+
98+
export const MY_SECOND_EXTENSION: NgxsDataExtension = [
99+
{
100+
provide: NGXS_PLUGINS,
101+
useClass: FeatureService,
102+
multi: true,
103+
},
104+
{
105+
provide: MyInjectableToken,
106+
useFactory: (): MyFactory => new MyFactory(),
107+
},
108+
];
109+
110+
NgxsDataPluginModule.forRoot([MY_FIRST_EXTENSION, MY_SECOND_EXTENSION]);
111+
```
112+
113+
**After:**
114+
115+
```ts
116+
import {makeEnvironmentProviders} from '@angular/core';
117+
import {withNgxsPlugin} from '@ngxs/store';
118+
119+
export const MY_FIRST_EXTENSION = withNgxsPlugin(MySuperService);
120+
121+
export const MY_SECOND_EXTENSION = makeEnvironmentProviders([
122+
withNgxsPlugin(FeatureService),
123+
{
124+
provide: MyInjectableToken,
125+
useFactory: (): MyFactory => new MyFactory(),
126+
},
127+
]);
128+
129+
provideNgxsDataPlugin(MY_FIRST_EXTENSION, MY_SECOND_EXTENSION);
130+
```
131+
132+
### Virtual Table changes and deprecations
133+
134+
- `TableBuilderModule.forRoot()` module provider has been replaced by `provideVirtualTable()` environment provider.
135+
- `TableBuilderModule` has been replaced by `VirtualTable` readonly array of standalone component.
136+
137+
**Before:**
138+
139+
```ts
140+
import {TableBuilderModule} from '@angular-ru/cdk/virtual-table';
141+
142+
@Component({
143+
//...
144+
imports: [TableBuilderModule],
145+
})
146+
export class MyComponent {}
147+
```
148+
149+
**After:**
150+
151+
```ts
152+
import {VirtualTable} from '@angular-ru/cdk/virtual-table';
153+
154+
@Component({
155+
//...
156+
imports: [VirtualTable],
157+
})
158+
export class MyComponent {}
159+
```
160+
161+
- All decorator inputs have been replaced by signal inputs, so, to read an input value in your component, the input has
162+
to be called as a function.
163+
164+
**Before:**
165+
166+
```ts
167+
export class MyComponent {
168+
@ViewChild('table')
169+
table!: TableBuilder<PlainObject>;
170+
171+
constructor() {
172+
// "source" was a normal decorated input
173+
console.log('source:', this.table.source);
174+
}
175+
}
176+
```
177+
178+
**After:**
179+
180+
```ts
181+
export class MyComponent {
182+
@ViewChild('table')
183+
table!: TableBuilder<PlainObject>;
184+
185+
constructor() {
186+
// "source" is now a signal input
187+
console.log('source:', this.table.source());
188+
}
189+
}
190+
```
191+
192+
- Some deprecated properties, methods and pipes have been removed:
193+
- `table.selectionEntries` property has been removed. Use `table.selectedKeyList` instead.
194+
- `tableSelectedItems` pipe has been removed. Use `mapToTableEntries` pipe instead.
195+
196+
**Before:**
197+
198+
```html
199+
<p>Selected items: {{ (table?.selectionEntries | tableSelectedItems).length }}</p>
200+
```
201+
202+
**After:**
203+
204+
```html
205+
<p>Selected items: {{ (table?.selectedKeyList | mapToTableEntries).length }}</p>
206+
```
207+
208+
- `table.selectedItems` property has been removed. Use `table.getSelectedItems()` method instead.

‎docs/ngxs/extension-api.md‎

Lines changed: 3 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -21,21 +21,12 @@ export const appConfig: ApplicationConfig = {
2121

2222
```typescript
2323
import {makeEnvironmentProviders} from '@angular/core';
24+
import {withNgxsPlugin} from '@ngxs/store';
2425

25-
export const MY_FIRST_EXTENSION = makeEnvironmentProviders([
26-
{
27-
provide: NGXS_PLUGINS,
28-
useClass: MySuperService,
29-
multi: true,
30-
},
31-
]);
26+
export const MY_FIRST_EXTENSION = withNgxsPlugin(MySuperService);
3227

3328
export const MY_SECOND_EXTENSION = makeEnvironmentProviders([
34-
{
35-
provide: NGXS_PLUGINS,
36-
useClass: FeatureService,
37-
multi: true,
38-
},
29+
withNgxsPlugin(FeatureService),
3930
{
4031
provide: MyInjectableToken,
4132
useFactory: (): MyFactory => new MyFactory(),

‎libs/ngxs/tokens/symbols/ngxs-data-exceptions.ts‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,21 +5,21 @@ export const enum NgxsDataExceptions {
55
NGXS_PERSISTENCE_STATE = '@Persistence should be add before decorator @State and @StateRepository',
66
NGXS_DATA_STATE = '@StateRepository should be add before decorator @State',
77
NGXS_DATA_STATE_NAME_NOT_FOUND = 'State name not provided in class',
8-
NGXS_DATA_PROVIDER_EXCEPTION = 'Metadata not created \n Maybe you forgot to provide NgxsDataPlugin' +
8+
NGXS_DATA_PROVIDER_EXCEPTION = 'Metadata was not created \n Maybe you forgot to provide NgxsDataPlugin' +
99
'\n Also, you cannot use this.ctx.* until the application is fully rendered ' +
1010
'\n (use by default ngxsOnInit(ctx: StateContext), or ngxsAfterBootstrap(ctx: StateContext) !!!',
11-
NGXS_DATA_STATE_DECORATOR = 'You forgot add decorator @StateRepository or initialize state!' +
11+
NGXS_DATA_STATE_DECORATOR = 'You forgot to add decorator @StateRepository or initialize state!' +
1212
'\nExample: provideStore([StateA]), or provideStates([StateB])',
1313
NGXS_DATA_STATIC_ACTION = 'Cannot support static methods with @DataAction()',
1414
NGXS_DATA_ACTION = '@DataAction() can only decorate a method implementation',
1515
NGXS_DATA_ASYNC_ACTION_RETURN_TYPE = 'WARNING: If you use asynchronous actions' +
1616
' `@Debounce() @DataAction()` the return result type should only void instead:',
17-
NGXS_PERSISTENCE_CONTAINER = 'You forgot provide NgxsDataPlugin or NgxsDataStorage!!! Example: \n' +
17+
NGXS_PERSISTENCE_CONTAINER = 'You forgot to provide NgxsDataPlugin or NgxsDataStorage!!! Example:\n' +
1818
'\nexport const appConfig: ApplicationConfig = {' +
1919
'\n providers: [' +
2020
'\n provideNgxsDataPlugin(withNgxsDataStorage()) ' +
21-
'\n ]\n' +
22-
'};',
21+
'\n ]' +
22+
'\n}\n\n;',
2323
NGXS_PERSISTENCE_ENGINE = 'Not found storage engine from `existingEngine` or not found instance after injecting by `useClass`.',
2424
NGXS_PERSISTENCE_SERIALIZE = 'Error occurred while serializing value',
2525
NGXS_PERSISTENCE_DESERIALIZE = 'Error occurred while deserializing value',

0 commit comments

Comments
 (0)