feat(angular): ship Ionic components as Angular standalone components (ionic-team#28311)

Issue number: N/A

---------

<!-- Please do not submit updates to dependencies unless it fixes an
issue. -->

<!-- Please try to limit your pull request to one type (bugfix, feature,
etc). Submit multiple pull requests if needed. -->

## What is the current behavior?
<!-- Please describe the current behavior that you are modifying. -->

**1. Bundle Size Reductions**

All Ionic UI components and Ionicons are added to the final bundle of an
Ionic Angular application. This is because all components and icons are
lazily loaded as needed. This prevents the compiler from properly tree
shaking applications. This does not cause all components and icons to be
loaded on application start, but it does increase the size of the final
app output that all users need to download.

**Related Issues**

ionic-team/ionicons#910

ionic-team/ionicons#536

ionic-team#27280

ionic-team#24352

**2. Standalone Component Support**

Standalone Components are a stable API as of Angular 15. The Ionic
starter apps on the CLI have NgModule and Standalone options, but all of
the Ionic components are still lazily/dynamically loaded using
`IonicModule`. Standalone components in Ionic also enable support for
new Angular features such as bundling with ESBuild instead of Webpack.
ESBuild does not work in Ionic Angular right now because components
cannot be statically analyzed since they are dynamically imported.

We added preliminary support for standalone components in Ionic v6.3.0.
This enabled developers to use their own custom standalone components
when routing with `ion-router-outlet`. However, we did not ship
standalone components for Ionic's UI components.

**Related Issues**

ionic-team#25404

ionic-team#27251

ionic-team#27387

**3. Faster Component Load Times**

Since Ionic Angular components are lazily loaded, they also need to be
hydrated. However, this hydration does not happen immediately which
prevents components from being usable for multiple frames.

**Related Issues**

ionic-team#24352

ionic-team#26474

## What is the new behavior?
<!-- Please describe the behavior or changes that are being added by
this PR. -->

- Ionic components and directives are accessible as Angular standalone
components/directives

## Does this introduce a breaking change?

- [ ] Yes
- [x] No

<!-- If this introduces a breaking change, please describe the impact
and migration path for existing applications below. -->


## Other information

<!-- Any other information that is important to this PR such as
screenshots of how the component looks before and after the change. -->

Associated documentation branch:
https://github.com/ionic-team/ionic-docs/tree/feature-7.5

---------

Co-authored-by: Maria Hutt <[email protected]>
Co-authored-by: Sean Perkins <[email protected]>
Co-authored-by: Amanda Johnston <[email protected]>
Co-authored-by: Maria Hutt <[email protected]>
Co-authored-by: Sean Perkins <[email protected]>

Author: 4 people

core/stencil.config.ts

@@ -7,6 +7,71 @@ import { vueOutputTarget } from '@stencil/vue-output-target';
 // @ts-ignore
 import { apiSpecGenerator } from './scripts/api-spec-generator';
 
+const componentCorePackage = '@ionic/core';
+
+const getAngularOutputTargets = () => {
+  const excludeComponents = [
+    // overlays that accept user components
+    'ion-modal',
+    'ion-popover',
+
+    // navigation
+    'ion-router',
+    'ion-route',
+    'ion-route-redirect',
+    'ion-router-link',
+    'ion-router-outlet',
+    'ion-nav',
+    'ion-back-button',
+
+    // tabs
+    'ion-tabs',
+    'ion-tab',
+
+    // auxiliar
+    'ion-picker-column',
+  ]
+  return [
+    angularOutputTarget({
+      componentCorePackage,
+      directivesProxyFile: '../packages/angular/src/directives/proxies.ts',
+      directivesArrayFile: '../packages/angular/src/directives/proxies-list.ts',
+      excludeComponents,
+      outputType: 'component',
+    }),
+    angularOutputTarget({
+      componentCorePackage,
+      directivesProxyFile: '../packages/angular/standalone/src/directives/proxies.ts',
+      excludeComponents: [
+        ...excludeComponents,
+        /**
+         * IonIcon is a special case because it does not come
+         * from the `@ionic/core` package, so generating proxies that
+         * are reliant on the CE build will reference the wrong
+         * import location.
+         */
+        'ion-icon',
+        /**
+         * Value Accessors are manually implemented in the `@ionic/angular/standalone` package.
+         */
+        'ion-input',
+        'ion-textarea',
+        'ion-searchbar',
+        'ion-datetime',
+        'ion-radio',
+        'ion-segment',
+        'ion-checkbox',
+        'ion-toggle',
+        'ion-range',
+        'ion-radio-group',
+        'ion-select'
+
+      ],
+      outputType: 'standalone',
+    })
+  ];
+}
+
 export const config: Config = {
   autoprefixCss: true,
   sourceMap: false,
@@ -61,7 +126,7 @@ export const config: Config = {
   ],
   outputTargets: [
     reactOutputTarget({
-      componentCorePackage: '@ionic/core',
+      componentCorePackage,
       includeImportCustomElements: true,
       includePolyfills: false,
       includeDefineCustomElements: false,
@@ -98,7 +163,7 @@ export const config: Config = {
       ]
     }),
     vueOutputTarget({
-      componentCorePackage: '@ionic/core',
+      componentCorePackage,
       includeImportCustomElements: true,
       includePolyfills: false,
       includeDefineCustomElements: false,
@@ -182,30 +247,7 @@ export const config: Config = {
     //   type: 'stats',
     //   file: 'stats.json'
     // },
-    angularOutputTarget({
-      componentCorePackage: '@ionic/core',
-      directivesProxyFile: '../packages/angular/src/directives/proxies.ts',
-      directivesArrayFile: '../packages/angular/src/directives/proxies-list.ts',
-      excludeComponents: [
-        // overlays that accept user components
-        'ion-modal',
-        'ion-popover',
-
-        // navigation
-        'ion-router',
-        'ion-route',
-        'ion-route-redirect',
-        'ion-router-link',
-        'ion-router-outlet',
-
-        // tabs
-        'ion-tabs',
-        'ion-tab',
-
-        // auxiliar
-        'ion-picker-column',
-      ],
-    }),
+    ...getAngularOutputTargets(),
   ],
   buildEs5: 'prod',
   testing: {

packages/angular/README.md

@@ -52,3 +52,23 @@ $ npx schematics @ionic/angular:ng-add
 
 
 You'll now be able to add ionic components to a vanilla Angular app setup.
+
+## Project Structure
+
+**common**
+
+This is where logic that is shared between lazy loaded and standalone components live. For example, the lazy loaded IonPopover and standalone IonPopover components extend from a base IonPopover implementation that exists in this directory.
+
+**Note:** This directory exposes internal APIs and is only accessed in the `standalone` and `src` submodules. Ionic developers should never import directly from `@ionic/angular/common`. Instead, they should import from `@ionic/angular` or `@ionic/angular/standalone`.
+
+**standalone**
+
+This is where the standalone component implementations live. It was added as a separate entry point to avoid any lazy loaded logic from accidentally being pulled in to the final build. Having a separate directory allows the lazy loaded implementation to remain accessible from `@ionic/angular` for backwards compatibility.
+
+Ionic developers can access this by importing from `@ionic/angular/standalone`.
+
+**src**
+
+This is where the lazy loaded component implementations live.
+
+Ionic developers can access this by importing from `@ionic/angular`.

packages/angular/common/ng-package.json

@@ -0,0 +1,5 @@
+{
+  "lib": {
+    "entryFile": "src/index.ts"
+  },
+}

packages/angular/common/src/directives/control-value-accessors/index.ts

@@ -0,0 +1 @@
+export * from './value-accessor';

packages/angular/src/directives/control-value-accessors/value-accessor.ts renamed to packages/angular/common/src/directives/control-value-accessors/value-accessor.ts

@@ -2,7 +2,7 @@ import { AfterViewInit, ElementRef, Injector, OnDestroy, Directive, HostListener
 import { ControlValueAccessor, NgControl } from '@angular/forms';
 import { Subscription } from 'rxjs';
 
-import { raf } from '../../util/util';
+import { raf } from '../../utils/util';
 
 // TODO(FW-2827): types
 
@@ -17,11 +17,11 @@ export class ValueAccessor implements ControlValueAccessor, AfterViewInit, OnDes
   protected lastValue: any;
   private statusChanges?: Subscription;
 
-  constructor(protected injector: Injector, protected el: ElementRef) {}
+  constructor(protected injector: Injector, protected elementRef: ElementRef) {}
 
   writeValue(value: any): void {
-    this.el.nativeElement.value = this.lastValue = value;
-    setIonicClasses(this.el);
+    this.elementRef.nativeElement.value = this.lastValue = value;
+    setIonicClasses(this.elementRef);
   }
 
   /**
@@ -38,20 +38,20 @@ export class ValueAccessor implements ControlValueAccessor, AfterViewInit, OnDes
    * @param value The new value of the control.
    */
   handleValueChange(el: HTMLElement, value: any): void {
-    if (el === this.el.nativeElement) {
+    if (el === this.elementRef.nativeElement) {
       if (value !== this.lastValue) {
         this.lastValue = value;
         this.onChange(value);
       }
-      setIonicClasses(this.el);
+      setIonicClasses(this.elementRef);
     }
   }
 
   @HostListener('ionBlur', ['$event.target'])
   _handleBlurEvent(el: any): void {
-    if (el === this.el.nativeElement) {
+    if (el === this.elementRef.nativeElement) {
       this.onTouched();
-      setIonicClasses(this.el);
+      setIonicClasses(this.elementRef);
     }
   }
 
@@ -64,7 +64,7 @@ export class ValueAccessor implements ControlValueAccessor, AfterViewInit, OnDes
   }
 
   setDisabledState(isDisabled: boolean): void {
-    this.el.nativeElement.disabled = isDisabled;
+    this.elementRef.nativeElement.disabled = isDisabled;
   }
 
   ngOnDestroy(): void {
@@ -87,7 +87,7 @@ export class ValueAccessor implements ControlValueAccessor, AfterViewInit, OnDes
 
     // Listen for changes in validity, disabled, or pending states
     if (ngControl.statusChanges) {
-      this.statusChanges = ngControl.statusChanges.subscribe(() => setIonicClasses(this.el));
+      this.statusChanges = ngControl.statusChanges.subscribe(() => setIonicClasses(this.elementRef));
     }
 
     /**
@@ -102,7 +102,7 @@ export class ValueAccessor implements ControlValueAccessor, AfterViewInit, OnDes
           const oldFn = formControl[method].bind(formControl);
           formControl[method] = (...params: any[]) => {
             oldFn(...params);
-            setIonicClasses(this.el);
+            setIonicClasses(this.elementRef);
           };
         }
       });
@@ -129,7 +129,7 @@ export const setIonicClasses = (element: ElementRef): void => {
 
 const getClasses = (element: HTMLElement) => {
   const classList = element.classList;
-  const classes = [];
+  const classes: string[] = [];
   for (let i = 0; i < classList.length; i++) {
     const item = classList.item(i);
     if (item !== null && startsWith(item, 'ng-')) {

packages/angular/common/src/directives/navigation/back-button.ts

@@ -0,0 +1,61 @@
+import { HostListener, Input, Optional, ElementRef, NgZone, ChangeDetectorRef, Directive } from '@angular/core';
+import type { Components } from '@ionic/core';
+import type { AnimationBuilder } from '@ionic/core/components';
+
+import { Config } from '../../providers/config';
+import { NavController } from '../../providers/nav-controller';
+import { ProxyCmp } from '../../utils/proxy';
+
+import { IonRouterOutlet } from './router-outlet';
+
+const BACK_BUTTON_INPUTS = ['color', 'defaultHref', 'disabled', 'icon', 'mode', 'routerAnimation', 'text', 'type'];
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export declare interface IonBackButton extends Components.IonBackButton {}
+
+@ProxyCmp({
+  inputs: BACK_BUTTON_INPUTS,
+})
+@Directive({
+  // eslint-disable-next-line @angular-eslint/no-inputs-metadata-property
+  inputs: BACK_BUTTON_INPUTS,
+})
+// eslint-disable-next-line @angular-eslint/directive-class-suffix
+export class IonBackButton {
+  @Input()
+  defaultHref: string | undefined;
+
+  @Input()
+  routerAnimation: AnimationBuilder | undefined;
+
+  protected el: HTMLElement;
+
+  constructor(
+    @Optional() private routerOutlet: IonRouterOutlet,
+    private navCtrl: NavController,
+    private config: Config,
+    private r: ElementRef,
+    protected z: NgZone,
+    c: ChangeDetectorRef
+  ) {
+    c.detach();
+    this.el = this.r.nativeElement;
+  }
+
+  /**
+   * @internal
+   */
+  @HostListener('click', ['$event'])
+  onClick(ev: Event): void {
+    const defaultHref = this.defaultHref || this.config.get('backButtonDefaultHref');
+
+    if (this.routerOutlet?.canGoBack()) {
+      this.navCtrl.setDirection('back', undefined, undefined, this.routerAnimation);
+      this.routerOutlet.pop();
+      ev.preventDefault();
+    } else if (defaultHref != null) {
+      this.navCtrl.navigateBack(defaultHref, { animation: this.routerAnimation });
+      ev.preventDefault();
+    }
+  }
+}

packages/angular/src/directives/navigation/nav-params.ts renamed to packages/angular/common/src/directives/navigation/nav-params.ts

@@ -0,0 +1,52 @@
+import { ElementRef, Injector, EnvironmentInjector, NgZone, ChangeDetectorRef, Directive } from '@angular/core';
+import type { Components } from '@ionic/core';
+
+import { AngularDelegate } from '../../providers/angular-delegate';
+import { ProxyCmp, proxyOutputs } from '../../utils/proxy';
+
+const NAV_INPUTS = ['animated', 'animation', 'root', 'rootParams', 'swipeGesture'];
+
+const NAV_METHODS = [
+  'push',
+  'insert',
+  'insertPages',
+  'pop',
+  'popTo',
+  'popToRoot',
+  'removeIndex',
+  'setRoot',
+  'setPages',
+  'getActive',
+  'getByIndex',
+  'canGoBack',
+  'getPrevious',
+];
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export declare interface IonNav extends Components.IonNav {}
+
+@ProxyCmp({
+  inputs: NAV_INPUTS,
+  methods: NAV_METHODS,
+})
+@Directive({
+  // eslint-disable-next-line @angular-eslint/no-inputs-metadata-property
+  inputs: NAV_INPUTS,
+})
+// eslint-disable-next-line @angular-eslint/directive-class-suffix
+export class IonNav {
+  protected el: HTMLElement;
+  constructor(
+    ref: ElementRef,
+    environmentInjector: EnvironmentInjector,
+    injector: Injector,
+    angularDelegate: AngularDelegate,
+    protected z: NgZone,
+    c: ChangeDetectorRef
+  ) {
+    c.detach();
+    this.el = ref.nativeElement;
+    ref.nativeElement.delegate = angularDelegate.create(environmentInjector, injector);
+    proxyOutputs(this, this.el, ['ionNavDidChange', 'ionNavWillChange']);
+  }
+}