refactor: Abstracted ElementInternals API into controller (#1749)

Author: rkaraivanov

src/components/avatar/avatar.ts

@@ -1,9 +1,8 @@
-import { html, LitElement, nothing } from 'lit';
+import { html, LitElement, nothing, type PropertyValues } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
-
 import { themes } from '../../theming/theming-decorator.js';
-import { watch } from '../common/decorators/watch.js';
+import { addInternalsController } from '../common/controllers/internals.js';
 import { registerComponent } from '../common/definitions/register.js';
 import type { AvatarShape } from '../types.js';
 import { styles } from './themes/avatar.base.css.js';
@@ -29,35 +28,40 @@ export default class IgcAvatarComponent extends LitElement {
   public static override styles = [styles, shared];
 
   /* blazorSuppress */
-  public static register() {
+  public static register(): void {
     registerComponent(IgcAvatarComponent);
   }
 
-  private __internals: ElementInternals;
+  private readonly _internals = addInternalsController(this, {
+    initialARIA: {
+      role: 'image',
+      ariaLabel: 'avatar',
+    },
+  });
 
   @state()
-  private hasError = false;
+  private _hasError = false;
 
   /**
    * The image source to use.
    * @attr
    */
   @property()
-  public src!: string;
+  public src?: string;
 
   /**
    * Alternative text for the image.
    * @attr
    */
   @property()
-  public alt!: string;
+  public alt?: string;
 
   /**
    * Initials to use as a fallback when no image is available.
    * @attr
    */
   @property()
-  public initials!: string;
+  public initials?: string;
 
   /**
    * The shape of the avatar.
@@ -66,27 +70,20 @@ export default class IgcAvatarComponent extends LitElement {
   @property({ reflect: true })
   public shape: AvatarShape = 'square';
 
-  constructor() {
-    super();
-
-    this.__internals = this.attachInternals();
-    this.__internals.role = 'img';
-    this.__internals.ariaLabel = 'avatar';
-  }
-
-  @watch('initials')
-  @watch('alt')
-  protected roleDescriptionChange() {
-    this.__internals.ariaRoleDescription = this.alt ?? this.initials;
-  }
+  protected override willUpdate(changedProperties: PropertyValues<this>): void {
+    if (changedProperties.has('initials') || changedProperties.has('alt')) {
+      this._internals.setARIA({
+        ariaRoleDescription: this.alt ?? this.initials,
+      });
+    }
 
-  @watch('src')
-  protected handleErrorState() {
-    this.hasError = false;
+    if (changedProperties.has('src')) {
+      this._hasError = false;
+    }
   }
 
-  protected handleError() {
-    this.hasError = true;
+  protected _handleError(): void {
+    this._hasError = true;
   }
 
   protected override render() {
@@ -95,13 +92,13 @@ export default class IgcAvatarComponent extends LitElement {
         ${this.initials
           ? html`<span part="initials">${this.initials}</span>`
           : html`<slot></slot>`}
-        ${this.src && !this.hasError
+        ${this.src && !this._hasError
           ? html`
               <img
                 part="image"
                 alt=${ifDefined(this.alt)}
                 src=${ifDefined(this.src)}
-                @error=${this.handleError}
+                @error=${this._handleError}
               />
             `
           : nothing}

src/components/badge/badge.ts

@@ -1,8 +1,7 @@
-import { html, LitElement } from 'lit';
+import { html, LitElement, type PropertyValues } from 'lit';
 import { property } from 'lit/decorators.js';
-
 import { themes } from '../../theming/theming-decorator.js';
-import { watch } from '../common/decorators/watch.js';
+import { addInternalsController } from '../common/controllers/internals.js';
 import { registerComponent } from '../common/definitions/register.js';
 import type { BadgeShape, StyleVariant } from '../types.js';
 import { styles } from './themes/badge.base.css.js';
@@ -25,11 +24,13 @@ export default class IgcBadgeComponent extends LitElement {
   public static override styles = [styles, shared];
 
   /* blazorSuppress */
-  public static register() {
+  public static register(): void {
     registerComponent(IgcBadgeComponent);
   }
 
-  private __internals: ElementInternals;
+  private readonly _internals = addInternalsController(this, {
+    initialARIA: { role: 'status' },
+  });
 
   /**
    * The type of badge.
@@ -52,15 +53,10 @@ export default class IgcBadgeComponent extends LitElement {
   @property({ reflect: true })
   public shape: BadgeShape = 'rounded';
 
-  constructor() {
-    super();
-    this.__internals = this.attachInternals();
-    this.__internals.role = 'status';
-  }
-
-  @watch('variant')
-  protected variantChange() {
-    this.__internals.ariaRoleDescription = `badge ${this.variant}`;
+  protected override willUpdate(changedProperties: PropertyValues<this>): void {
+    if (changedProperties.has('variant')) {
+      this._internals.setARIA({ ariaRoleDescription: `badge ${this.variant}` });
+    }
   }
 
   protected override render() {

src/components/banner/banner.ts

@@ -6,6 +6,7 @@ import { addAnimationController } from '../../animations/player.js';
 import { growVerIn, growVerOut } from '../../animations/presets/grow/index.js';
 import { themes } from '../../theming/theming-decorator.js';
 import IgcButtonComponent from '../button/button.js';
+import { addInternalsController } from '../common/controllers/internals.js';
 import { registerComponent } from '../common/definitions/register.js';
 import type { Constructor } from '../common/mixins/constructor.js';
 import { EventEmitterMixin } from '../common/mixins/event-emitter.js';
@@ -46,13 +47,15 @@ export default class IgcBannerComponent extends EventEmitterMixin<
   public static styles = [styles];
 
   /* blazorSuppress */
-  public static register() {
+  public static register(): void {
     registerComponent(IgcBannerComponent, IgcButtonComponent);
   }
 
-  private _internals: ElementInternals;
-  private _bannerRef: Ref<HTMLElement> = createRef();
-  private _animationPlayer = addAnimationController(this, this._bannerRef);
+  private readonly _bannerRef: Ref<HTMLElement> = createRef();
+  private readonly _animationPlayer = addAnimationController(
+    this,
+    this._bannerRef
+  );
 
   /**
    * Determines whether the banner is being shown/hidden.
@@ -63,10 +66,13 @@ export default class IgcBannerComponent extends EventEmitterMixin<
 
   constructor() {
     super();
-    this._internals = this.attachInternals();
 
-    this._internals.role = 'status';
-    this._internals.ariaLive = 'polite';
+    addInternalsController(this, {
+      initialARIA: {
+        role: 'status',
+        ariaLive: 'polite',
+      },
+    });
   }
 
   /** Shows the banner if not already shown. Returns `true` when the animation has completed. */

src/components/button/button-base.ts

@@ -2,6 +2,7 @@ import { html, LitElement, nothing, type TemplateResult } from 'lit';
 import { property, query } from 'lit/decorators.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
 import { addKeyboardFocusRing } from '../common/controllers/focus-ring.js';
+import { addInternalsController } from '../common/controllers/internals.js';
 import { blazorDeepImport } from '../common/decorators/blazorDeepImport.js';
 import type { Constructor } from '../common/mixins/constructor.js';
 import { EventEmitterMixin } from '../common//mixins/event-emitter.js';
@@ -27,8 +28,7 @@ export abstract class IgcButtonBaseComponent extends EventEmitterMixin<
     delegatesFocus: true,
   };
 
-  protected readonly __internals: ElementInternals;
-
+  protected readonly _internals = addInternalsController(this);
   private readonly _focusRingManager = addKeyboardFocusRing(this);
 
   protected _disabled = false;
@@ -49,14 +49,14 @@ export abstract class IgcButtonBaseComponent extends EventEmitterMixin<
    * @attr
    */
   @property()
-  public href!: string;
+  public href?: string;
 
   /**
    * Prompts to save the linked URL instead of navigating to it.
    * @attr
    */
   @property()
-  public download!: string;
+  public download?: string;
 
   /**
    * Where to display the linked URL, as the name for a browsing context.
@@ -71,7 +71,7 @@ export abstract class IgcButtonBaseComponent extends EventEmitterMixin<
    * @attr
    */
   @property()
-  public rel!: string;
+  public rel?: string;
 
   /**
    * The disabled state of the component
@@ -91,12 +91,7 @@ export abstract class IgcButtonBaseComponent extends EventEmitterMixin<
   /* alternateType: object */
   /** Returns the HTMLFormElement associated with this element. */
   public get form(): HTMLFormElement | null {
-    return this.__internals.form;
-  }
-
-  constructor() {
-    super();
-    this.__internals = this.attachInternals();
+    return this._internals.form;
   }
 
   /* alternateName: focusComponent */

src/components/button/button.ts

@@ -29,7 +29,7 @@ export default class IgcButtonComponent extends IgcButtonBaseComponent {
   protected static styles = [styles, shared];
 
   /* blazorSuppress */
-  public static register() {
+  public static register(): void {
     registerComponent(IgcButtonComponent);
   }
 

src/components/button/icon-button.ts

@@ -28,7 +28,7 @@ export default class IgcIconButtonComponent extends IgcButtonBaseComponent {
   protected static styles = [styles, shared];
 
   /* blazorSuppress */
-  public static register() {
+  public static register(): void {
     registerComponent(IgcIconButtonComponent, IgcIconComponent);
   }
 
@@ -38,14 +38,14 @@ export default class IgcIconButtonComponent extends IgcButtonBaseComponent {
    * @attr
    */
   @property()
-  public name!: string;
+  public name?: string;
 
   /**
    * The name of the icon collection.
    * @attr
    */
   @property()
-  public collection!: string;
+  public collection?: string;
 
   /**
    * Whether to flip the icon button. Useful for RTL layouts.

src/components/carousel/carousel-indicator.ts

@@ -1,8 +1,9 @@
 import { consume } from '@lit/context';
-import { html, LitElement } from 'lit';
+import { html, LitElement, type PropertyValues } from 'lit';
 import { property } from 'lit/decorators.js';
 import { styleMap } from 'lit/directives/style-map.js';
 import { carouselContext } from '../common/context.js';
+import { addInternalsController } from '../common/controllers/internals.js';
 import { registerComponent } from '../common/definitions/register.js';
 import { formatString } from '../common/util.js';
 import type IgcCarouselComponent from './carousel.js';
@@ -25,51 +26,45 @@ export default class IgcCarouselIndicatorComponent extends LitElement {
   public static override styles = styles;
 
   /* blazorSuppress */
-  public static register() {
+  public static register(): void {
     registerComponent(IgcCarouselIndicatorComponent);
   }
 
-  private _active = false;
-  private _internals: ElementInternals;
+  private readonly _internals = addInternalsController(this, {
+    initialARIA: { role: 'tab' },
+  });
 
   @consume({ context: carouselContext, subscribe: true })
   private _carousel?: IgcCarouselComponent;
 
-  protected get _labelFormat() {
+  protected get _labelFormat(): string {
     return this._carousel ? this._carousel.indicatorsLabelFormat : '';
   }
 
   /* blazorSuppress */
   @property({ attribute: false })
-  public set active(value: boolean) {
-    this._active = Boolean(value);
-    this.tabIndex = this._active ? 0 : -1;
-    this._internals.ariaSelected = this._active.toString();
-  }
-
-  public get active(): boolean {
-    return this._active;
-  }
+  public active = false;
 
   /* blazorSuppress */
   @property({ attribute: false })
   public index = 0;
 
-  constructor() {
-    super();
-
-    this._internals = this.attachInternals();
-    this._internals.role = 'tab';
-  }
-
-  public override connectedCallback() {
+  /** @internal */
+  public override connectedCallback(): void {
     super.connectedCallback();
     this.role = 'tab';
     this.slot = this.slot || 'indicator';
   }
 
-  protected override willUpdate(): void {
-    this._internals.ariaLabel = formatString(this._labelFormat, this.index + 1);
+  protected override willUpdate(changedProperties: PropertyValues<this>): void {
+    if (changedProperties.has('active')) {
+      this.tabIndex = this.active ? 0 : -1;
+      this._internals.setARIA({ ariaSelected: this.active.toString() });
+    }
+
+    this._internals.setARIA({
+      ariaLabel: formatString(this._labelFormat, this.index + 1),
+    });
   }
 
   protected override render() {