feat!: migrate to Ionic 9 and support Angular 21-22

.github/workflows/lint.yml

@@ -34,7 +34,7 @@
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        project: [ demo, kit, photo-editor, scroll-header, scroll-strategies]
+        project: [demo, kit, photo-editor, scroll-header, scroll-strategies]
     steps:
       - uses: actions/checkout@v5
       - uses: actions/setup-node@v5
@@ -64,7 +64,37 @@
           cache-dependency-path: '**/package-lock.json'
       - run: npm ci
       - run: npm run test:actions
+  angular-21-compat:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 24.15.0
+          cache: npm
+          cache-dependency-path: '**/package-lock.json'
+      - run: npm ci
+      - name: Install the Angular 21 compatibility toolchain
+        run: >-
+          npm install --no-save --force
+          @angular/animations@^21.2.0
+          @angular/build@^21.2.0
+          @angular/cdk@^21.2.0
+          @angular/cli@^21.2.0
+          @angular/common@^21.2.0
+          @angular/compiler@^21.2.0
+          @angular/compiler-cli@^21.2.0
+          @angular/core@^21.2.0
+          @angular/forms@^21.2.0
+          @angular/platform-browser@^21.2.0
+          @angular/platform-browser-dynamic@^21.2.0
+          @angular/router@^21.2.0
+          @angular/service-worker@^21.2.0
+          ng-packagr@^21.2.0
+          typescript@~5.9.3
+      - name: Build libraries and consuming demo with Angular 21
+        run: npm run build
   e2e:
     runs-on: ubuntu-latest
     container:
       image: mcr.microsoft.com/playwright:v1.57.0-noble

README.md

@@ -2,20 +2,25 @@ These libraries is a collection of components and services that are useful for d
 
 Documentation: [Ionic Angular Kit](https://docs.rdlabo.dev/projects/ionic-angular-kit) · [Photo Editor](https://docs.rdlabo.dev/projects/ionic-angular-photo-editor) · [Scroll Header](https://docs.rdlabo.dev/projects/ionic-angular-scroll-header) · [Scroll Strategies](https://docs.rdlabo.dev/projects/ngx-cdk-scroll-strategies)
 
+Migration guide: [Angular 21–22 and Ionic 9](docs/migration.md)
+
 [Demo site is here.](https://rdlabo-ionic-angular-library.netlify.app/)
 
 ## Support Version
 
-| Angular | Package version |
-| ------- | --------------- |
-| v20     | 20.x.x          |
-| v19     | 19.x.x          |
-| v18     | 2.x.x           |
+| Angular | Ionic | Package version |
+| ------- | ----- | --------------- |
+| v21–22  | v9    | 22.x.x          |
+| v20     | v8    | 20.x.x          |
+| v19     | v8    | 19.x.x          |
+| v18     | v8    | 2.x.x           |
+
+Ionic 9 native applications require Capacitor 7 or later. See the [migration guide](docs/migration.md) before upgrading an existing application.
 
 ## packages
 
-| package name                        | description                                                                                | path                                                                                                                           |
-| ----------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| package name                        | description                                                                                | path                                                                                                                          |
+| ----------------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
 | @rdlabo/ionic-angular-kit           | Auth guards, Firebase flows, storage, overlay, HTTP interceptor, and other fleet helpers.  | [/projects/kit](https://github.com/rdlabo-dev/ionic-angular-library/tree/main/projects/kit#readme)                            |
 | @rdlabo/ionic-angular-photo-editor  | This is a photo editor and viewer for modal page of Ionic Angular project using Capacitor. | [/project/photo-editor](https://github.com/rdlabo-dev/ionic-angular-library/tree/main/projects/photo-editor#readme)           |
 | @rdlabo/ionic-angular-scroll-header | This is directive for scroll with Header.                                                  | [/project/scroll-header](https://github.com/rdlabo-dev/ionic-angular-library/tree/main/projects/scroll-header#readme)         |

docs/migration.md

@@ -0,0 +1,75 @@
+# Migration guide
+
+## Angular 21–22 and Ionic 9
+
+The 22.x package line supports Angular 21 and 22 with Ionic 9. Ionic 9 requires Angular 18 or later; native applications also require Capacitor 7 or later.
+
+Read the upstream [Ionic 9 breaking changes](https://github.com/ionic-team/ionic-framework/blob/main/BREAKING.md#version-9x) and the [Angular version compatibility table](https://angular.dev/reference/versions) before upgrading your application.
+
+### 1. Update dependencies
+
+Use matching Angular major versions throughout the application. Angular 22 uses TypeScript 6.0 and requires a supported Node.js release.
+
+```bash
+npx ng update @angular/core@22 @angular/cli@22
+npx @ionic/migrate
+```
+
+`@ionic/migrate` is the recommended path for Ionic applications: it updates the Ionic packages and applies the available source migrations. Review its changes together with the manual audit below. The migrator does not support Angular library workspaces such as this repository, so library maintainers must apply the Ionic changes manually.
+
+For a native application, upgrade Capacitor separately and follow its migration guide:
+
+```bash
+npm install @capacitor/core@^8 @capacitor/ios@^8 @capacitor/android@^8
+npm install --save-dev @capacitor/cli@^8
+npx cap migrate
+```
+
+Capacitor 7 and 8 are supported by these libraries. Keep all Capacitor core and plugin packages on compatible major versions.
+
+### 2. Update Ionic Angular imports
+
+Ionic 9 exports standalone components and providers from `@ionic/angular` by default. Replace imports from the old standalone entry point:
+
+```ts
+// Before
+import { IonContent, ModalController, provideIonicAngular } from '@ionic/angular/standalone';
+
+// After
+import { IonContent, ModalController, provideIonicAngular } from '@ionic/angular';
+```
+
+If the application intentionally uses lazy-loaded Ionic wrappers, import those wrappers from `@ionic/angular/lazy`. `IonicModule` still works in Ionic 9 but is deprecated; new and migrated applications should use `provideIonicAngular()`.
+
+### 3. Check change detection
+
+Angular 21 is zoneless by default. Angular 22 additionally defaults components without an explicit strategy to `OnPush`.
+
+Prefer signals for state changed after asynchronous work such as overlay dismissal, timers, RxJS subscriptions, or platform events. Otherwise call `ChangeDetectorRef.markForCheck()`. Run the Angular update migrations so existing components retain their intended change-detection behavior.
+
+### 4. Audit Ionic 9 component changes
+
+Check application templates, styles, and tests for the following Ionic 9 changes:
+
+- Replace `autocorrect="on"` or `autocorrect="off"` on `ion-input` and `ion-searchbar` with a boolean property binding, or omit it for the default `false` value.
+- Replace legacy picker components and controller APIs with the inline `ion-picker` component.
+- Set `handleBehavior="none"` on sheet modals only when the handle must retain its previous inert behavior; the new default is `cycle`.
+- Use `ion-router-outlet` for URL-based routing. `ion-nav` now manages only an imperative, URL-less navigation stack.
+- Do not rely on `ion-select` emitting `ionChange` when a confirmed value did not change. Use dismissal events when confirmation itself matters.
+- Do not rely on the `selected` dismissal role from the `ion-select` action-sheet interface; listen for `ionChange` when the selected value changes.
+- Check floating labels on `ion-input`, `ion-select`, and `ion-textarea` with slotted content. Slotted content alone no longer causes the label to float.
+- Review custom selectors and shadow-part styles for `ion-input`, `ion-select`, and `ion-textarea`, whose internal structures changed.
+- Review Material Design textarea layouts: the new minimum height is 72px.
+
+### 5. Verify the application
+
+Build and test both web and native targets after updating:
+
+```bash
+npm run lint
+npm test
+npm run build
+npx cap sync
+```
+
+Test modal sheets, form controls, select overlays, virtual scrolling, navigation gestures, and state updates that occur after asynchronous callbacks on each supported platform.