refactor: add simpler componentFocusable util (deprecates LoadableComponent)

packages/calcite-components/src/utils/component.spec.ts

@@ -1,6 +1,7 @@
 import { HTMLStencilElement } from "@stencil/core/internal";
 import { html } from "../../support/formatting";
-import { componentOnReady, getIconScale } from "./component";
+import * as componentUtils from "./component";
+const { componentFocusable, componentOnReady, getIconScale } = componentUtils;
 
 describe("getIconScale", () => {
   it('should return "m" when input is "l"', () => {
@@ -18,7 +19,7 @@ describe("componentOnReady", () => {
   let fakeComponent: HTMLElement;
 
   beforeEach(() => {
-    document.body.innerHTML = html` <fake-component></fake-component> `;
+    document.body.innerHTML = html`<fake-component></fake-component> `;
     fakeComponent = document.querySelector<HTMLElement>("fake-component");
 
     const originalRaf = globalThis.requestAnimationFrame;
@@ -49,3 +50,47 @@ describe("componentOnReady", () => {
     expect(requestAnimationFrameSpy).toHaveBeenCalled();
   });
 });
+
+describe("componentFocusable", () => {
+  let componentOnReadyStub: jest.SpyInstance;
+  let fakeComponent: HTMLStencilElement;
+  let forceUpdateSpy: jest.SpyInstance;
+  let requestAnimationFrameSpy: jest.SpyInstance;
+  let componentOnReadyResolver: (el: HTMLStencilElement) => void;
+
+  beforeEach(async () => {
+    document.body.innerHTML = html`<fake-component></fake-component> `;
+    fakeComponent = document.querySelector<HTMLStencilElement>("fake-component");
+
+    const componentOnReadyPromise = new Promise<HTMLStencilElement>(
+      (resolve: (el: HTMLStencilElement) => void) => (componentOnReadyResolver = resolve),
+    );
+    componentOnReadyStub = fakeComponent.componentOnReady = jest.fn(() => componentOnReadyPromise);
+    forceUpdateSpy = jest.spyOn(componentUtils, "forceUpdate").mockImplementation(jest.fn());
+
+    const originalRaf = globalThis.requestAnimationFrame;
+    requestAnimationFrameSpy = jest
+      .spyOn(globalThis, "requestAnimationFrame")
+      .mockImplementation((callback) => originalRaf(callback));
+  });
+
+  afterEach(() => {
+    requestAnimationFrameSpy.mockRestore();
+    forceUpdateSpy.mockRestore();
+  });
+
+  it("should resolve when ready and rendered", async () => {
+    const promise = componentFocusable(fakeComponent);
+    expect(promise).toBeInstanceOf(Promise);
+
+    expect(componentOnReadyStub).toHaveBeenCalled();
+    expect(requestAnimationFrameSpy).not.toHaveBeenCalled();
+    expect(forceUpdateSpy).not.toHaveBeenCalled();
+
+    componentOnReadyResolver(fakeComponent);
+    await promise;
+
+    expect(forceUpdateSpy).toHaveBeenCalled();
+    expect(requestAnimationFrameSpy).toHaveBeenCalled();
+  });
+});

packages/calcite-components/src/utils/component.ts

@@ -1,3 +1,4 @@
+import { Build, forceUpdate as stencilForceUpdate } from "@stencil/core";
 import { HTMLStencilElement } from "@stencil/core/internal";
 import { Scale } from "../components/interfaces";
 
@@ -21,3 +22,40 @@ export async function componentOnReady(el: HTMLElement): Promise<void> {
 function isStencilEl(el: HTMLElement): el is HTMLStencilElement {
   return typeof (el as HTMLStencilElement).componentOnReady === "function";
 }
+
+/**
+ * Exported for testing purposes only.
+ *
+ * @internal
+ */
+export const forceUpdate = Build.isTesting
+  ? stencilForceUpdate
+  : () => {
+      /* noop */
+    };
+
+/**
+ * This helper util can be used to ensuring the component is loaded and rendered by the browser (The "componentDidLoad" Stencil lifecycle method has been called and any internal elements are focusable).
+ *
+ * A component developer can await this method before proceeding with any logic that requires a component to be loaded first and then an internal element be focused.
+ *
+ * ```
+ * async setFocus(): Promise<void> {
+ *   await componentFocusable(this);
+ *   this.internalElement?.focus();
+ * }
+ * ```
+ *
+ * @param el the component's host element
+ * @returns Promise<void>
+ */
+export async function componentFocusable(el: HTMLElement): Promise<void> {
+  await componentOnReady(el);
+
+  if (!Build.isBrowser && !Build.isTesting) {
+    return;
+  }
+
+  forceUpdate(el);
+  return new Promise((resolve) => requestAnimationFrame(() => resolve()));
+}

packages/calcite-components/src/utils/loadable.ts

@@ -1,4 +1,4 @@
-import { Build, forceUpdate } from "@stencil/core";
+import { componentFocusable as componentFocusableReplacement } from "./component";
 
 /**
  * This helper adds support for knowing when a component has been loaded.
@@ -37,23 +37,30 @@ import { Build, forceUpdate } from "@stencil/core";
  *    await componentLoaded(this);
  *  }
  * ```
+ *
+ * @deprecated use `componentOnReady` from `components.ts` instead.
  */
 export interface LoadableComponent {
+  /**
+   * The host element.
+   */
+  el: HTMLElement;
+
   /**
    * Stencil lifecycle method.
    * https://stenciljs.com/docs/component-lifecycle#componentwillload
    *
    * Called once just after the component is first connected to the DOM. Since this method is only called once, it's a good place to load data asynchronously and to setup the state without triggering extra re-renders.
    */
-  componentWillLoad: () => Promise<void> | void;
+  componentWillLoad?: () => Promise<void> | void;
 
   /**
    * Stencil lifecycle method.
    * https://stenciljs.com/docs/component-lifecycle#componentdidload
    *
    * Called once just after the component is fully loaded and the first render() occurs.
    */
-  componentDidLoad: () => Promise<void> | void;
+  componentDidLoad?: () => Promise<void> | void;
 }
 
 const resolveMap = new WeakMap<LoadableComponent, (value: void | PromiseLike<void>) => void>();
@@ -72,6 +79,8 @@ const promiseMap = new WeakMap<LoadableComponent, Promise<void>>();
  * ```
  *
  * @param component
+ *
+ * @deprecated use `componentOnReady` from `components.ts` instead.
  */
 export function setUpLoadableComponent(component: LoadableComponent): void {
   promiseMap.set(component, new Promise((resolve) => resolveMap.set(component, resolve)));
@@ -89,6 +98,8 @@ export function setUpLoadableComponent(component: LoadableComponent): void {
  * ```
  *
  * @param component
+ *
+ * @deprecated use `componentOnReady` from `components.ts` instead.
  */
 export function setComponentLoaded(component: LoadableComponent): void {
   resolveMap.get(component)();
@@ -109,6 +120,8 @@ export function setComponentLoaded(component: LoadableComponent): void {
  *
  * @param component
  * @returns Promise<void>
+ *
+ * @deprecated use `componentOnReady` from `components.ts` instead.
  */
 export function componentLoaded(component: LoadableComponent): Promise<void> {
   return promiseMap.get(component);
@@ -117,7 +130,7 @@ export function componentLoaded(component: LoadableComponent): Promise<void> {
 /**
  * This helper util can be used to ensuring the component is loaded and rendered by the browser (The "componentDidLoad" Stencil lifecycle method has been called and any internal elements are focusable).
  *
- * Requires requires `LoadableComponent` to be implemented.
+ * Requires `LoadableComponent` to be implemented.
  *
  * A component developer can await this method before proceeding with any logic that requires a component to be loaded first and then an internal element be focused.
  *
@@ -130,14 +143,9 @@ export function componentLoaded(component: LoadableComponent): Promise<void> {
  *
  * @param component
  * @returns Promise<void>
+ *
+ * @deprecated use `componentFocusable` from `components.ts` instead.
  */
 export async function componentFocusable(component: LoadableComponent): Promise<void> {
-  await componentLoaded(component);
-
-  if (!Build.isBrowser) {
-    return;
-  }
-
-  forceUpdate(component);
-  return new Promise((resolve) => requestAnimationFrame(() => resolve()));
+  await componentFocusableReplacement(component.el);
 }