Skip to content

v22.0.0

Choose a tag to compare

View all tags
@rdlabo rdlabo released this 02 Sep 14:40
· 27 commits to main since this release
v22.0.0
995ed1e

Ionic 9, Angular 22, and a cleaner foundation for production Ionic apps

v22 is a major modernization of the entire rdlabo Ionic Angular library family. It adds Angular 21–22 and Ionic 9 support, makes optional features genuinely opt-in, introduces first-class Angular Signal Forms support, and strengthens the offline runtime with route isolation, faster reads, durable create delivery, and real SQLite contract tests.

All four packages continue to share one version line:

  • @rdlabo/ionic-angular-kit
  • @rdlabo/ionic-angular-photo-editor
  • @rdlabo/ionic-angular-scroll-header
  • @rdlabo/ngx-cdk-scroll-strategies

Highlights

Modern platform support

  • Angular 21 and 22
  • Ionic Angular 9
  • Capacitor 7 and 8 for native features
  • Minimum iOS/iPadOS deployment target: 16.4
  • Angular 21 compatibility is validated alongside the Angular 22 development workspace

A smaller, more explicit Photo Editor

Photo Editor is now split into focused secondary entry points for the editor, viewer, file loading, TUI adapter, and Capacitor camera adapter. Applications install and bundle only the implementations they use.

The release also adds typed modal results, explicit toolbar color schemes, package-prefixed selectors, accessible image alt text, typed PhotoLoadError codes, and a browser file picker that no longer requires a static input in index.html.

Angular Signal Forms for Ionic controls

The new @rdlabo/ionic-angular-kit/forms entry point connects Angular Signal Forms to Ionic form controls. It provides Ionic state classes and error text while preserving application-owned messages and localization.

Safer application updates and leaner Kit imports

  • provideKitAppUpdate({ strategy: 'background' }) checks for complete service-worker updates without blocking bootstrap or reloading after the user has started interacting.
  • Granular Ionic controller imports reduce the initial static JavaScript closure. In one production consumer, the measured reduction was approximately 851 kB (19.7%); actual results depend on the application bundle.

Stronger offline foundations

The offline runtime adds:

  • route-scoped isolated runtimes;
  • deferred authenticated remote initialization;
  • fastest-first and local-only reads;
  • immediate durable delivery for newly created generated identities;
  • serialized replica mutation and response projection;
  • stronger Outbox idempotency and concurrency guarantees; and
  • repository contract and rollback coverage against real SQLite.

Warning

The entire @rdlabo/ionic-angular-kit/offline entry point is experimental and is not covered by the Kit's SemVer compatibility guarantee. Its APIs, persistence schema, and synchronization behavior may change incompatibly in a minor or patch release. Pin the Kit to an exact version and review the migration guide before every upgrade.

Upgrade guide

1. Upgrade the application platform first

  1. Upgrade the host application to Angular 21 or 22 using the Angular Update Guide.
  2. Migrate the application to Ionic 9 with npx @ionic/migrate, then review the Ionic breaking changes.
  3. For native applications, upgrade to Capacitor 7 or 8 using the Capacitor upgrade guides.
  4. Set platform :ios, '16.4' in the Podfile and IPHONEOS_DEPLOYMENT_TARGET = 16.4 in the Xcode project.

2. Install the v22 libraries you use

npm install @rdlabo/ionic-angular-kit@^22 \
  @rdlabo/ionic-angular-photo-editor@^22 \
  @rdlabo/ionic-angular-scroll-header@^22 \
  @rdlabo/ngx-cdk-scroll-strategies@^22

Omit unused packages. Keep all installed rdlabo libraries on the same release line.

Applications adopting the experimental offline entry point should pin the Kit exactly:

npm install --save-exact @rdlabo/ionic-angular-kit@22.0.0

3. Apply the consumer changes

Photo Editor

  • Move component and service imports to /editor, /viewer, and /file.
  • Configure optional implementations through /editor/tui and /file/capacitor.
  • Add the required toolbarColorScheme: 'light' | 'dark' to editor and viewer props.
  • Pass imageUrls explicitly to the viewer.
  • Replace legacy dismiss interfaces with PhotoEditorResult and PhotoViewerResult.
  • Replace mutable PhotoFileService defaults with providePhotoEditor(...).
  • Change loadPhoto(number) to loadPhoto({ limit, ... }) and handle typed PhotoLoadError codes.
  • Remove the static #browserPhotoUploader input from index.html.
  • Update direct-template selectors to <rdlabo-photo-editor> and <rdlabo-photo-viewer>.

Ionic Angular Kit

  • Remove kitAuthInput="autofill" and value-less kitAuthInput usage. Keep only explicit "email" or "email-remember" modes where email persistence is required.
  • Offline consumers can adopt the new read and synchronization APIs incrementally. Direct command and pull-attention mutations on OfflineRepository are deprecated; use OfflineSyncService.runSerializedReplicaMutation() with repository.transactReplica() for product-owned writes.

Scroll Header

Existing template directives remain compatible. Remove application calls or subclass overrides of directive ngOnInit() methods; Angular owns their lifecycle.

Scroll Strategies

  • Replace removed calcIndex calls with calculateItemCountForPixelDistance and revalidate thresholds because the corrected calculation is not a drop-in numeric rename.
  • Stop using _dynamicSizeVirtualScrollStrategyFactory and the directive's internal _scrollStrategy field.

For complete before/after examples and the full checklist, read the v21 → v22 migration guide.

Documentation

Quality and release confidence

v22 is covered by library unit tests, hydrated Ionic modal E2E tests, Angular 21 and 22 compatibility builds, packed-package consumer checks, optional-peer isolation checks, and real SQLite offline contract/concurrency tests.

Thank you to everyone building Ionic Angular applications with these packages. Feedback and reproducible bug reports are welcome in GitHub Issues.

Full Changelog: v21.7.0...v22.0.0

Assets 2
Loading