Add lazy utility to create lazy-loading UI components

Add a utility for creating components which are loaded only when rendered. When
first rendered, a lazy component displays a fallback while the real
implementation is fetched. It then renders the real component after the fetch
completes. If the component fails to load an an error fallback is rendered in
its place.

Author: robertknight

src/index.ts

@@ -21,6 +21,7 @@ export {
   formatRelativeDate,
   formatDateTime,
 } from './util/date-and-time';
+export { lazy } from './util/lazy';
 export { ListenerCollection } from './util/listener-collection';
 export { confirm } from './util/prompts';
 

src/util/lazy.tsx

@@ -0,0 +1,69 @@
+import type { ComponentChildren, FunctionalComponent, JSX } from 'preact';
+import { useState } from 'preact/hooks';
+
+export type LazyOptions<P> = {
+  /** Returns the content to render if the component is not yet loaded. */
+  fallback: (props: P) => ComponentChildren;
+  /** Returns the content to render if the component failed to load. */
+  errorFallback?: (props: P, err: Error) => ComponentChildren;
+};
+
+/**
+ * Create a lazy-loading version of a component.
+ *
+ * This utility allows deferring loading the code for a component until it is
+ * rendered. The returned component loads in two phases. In the first phase a
+ * placeholder is rendered and the {@link onLoad} callback is invoked to load
+ * the component. Then when the returned promise resolves, the placeholder is
+ * replaced with the real compoonent.
+ *
+ * @param displayName - Display name for the lazy wrapper component
+ * @param onLoad - A function which loads the JS component. This will usually
+ *   be an async function which does `import('path/to/module')` and then returns
+ *   one of the loaded module's exports.
+ * @param options - Options that specify what to render while the component is
+ *   loading or if it fails to load.
+ */
+export function lazy<P>(
+  displayName: string,
+  onLoad: () => Promise<FunctionalComponent<P>>,
+  { errorFallback, fallback }: LazyOptions<P>,
+) {
+  function Lazy(props: P & JSX.IntrinsicAttributes) {
+    const [component, setComponent] = useState<FunctionalComponent<P>>();
+    const [error, setError] = useState<Error | null>(null);
+    const [loading, setLoading] = useState(false);
+
+    if (error) {
+      return errorFallback ? (
+        errorFallback(props, error)
+      ) : (
+        <div>
+          <p>
+            There was a problem loading this content. Try refreshing the page.
+          </p>
+          <b>Details:</b> {error.message}
+        </div>
+      );
+    }
+    if (!component && !loading) {
+      setLoading(true);
+      onLoad()
+        .then(component => {
+          setComponent(() => component);
+        })
+        .catch(setError)
+        .finally(() => {
+          setLoading(false);
+        });
+    }
+    if (component) {
+      const Component = component;
+      return <Component {...props} />;
+    }
+    return fallback(props);
+  }
+
+  Lazy.displayName = `Lazy(${displayName})`;
+  return Lazy;
+}

src/util/test/lazy-test.js

@@ -0,0 +1,129 @@
+import { delay, mount } from '@hypothesis/frontend-testing';
+
+import { lazy } from '../lazy';
+
+describe('lazy', () => {
+  let fakeComponent;
+  let fakeLoader;
+  let LazyComponent;
+
+  beforeEach(() => {
+    fakeComponent = ({ text }) => (
+      <div data-testid="loaded-component">{text}</div>
+    );
+    fakeLoader = sinon.stub();
+    LazyComponent = lazy('TestComponent', fakeLoader, {
+      fallback: ({ text }) => <div data-testid="fallback">{text}</div>,
+      errorFallback: ({ text }, error) => (
+        <div data-testid="error-fallback">
+          {text} - Error: {error.message}
+        </div>
+      ),
+    });
+  });
+
+  afterEach(() => {
+    sinon.restore();
+  });
+
+  it('renders fallback initially', () => {
+    fakeLoader.returns(Promise.resolve(fakeComponent));
+    const wrapper = mount(<LazyComponent text="test" />);
+
+    assert.isTrue(wrapper.exists('[data-testid="fallback"]'));
+    assert.equal(wrapper.find('[data-testid="fallback"]').text(), 'test');
+  });
+
+  it('renders loaded component after loading completes', async () => {
+    fakeLoader.returns(Promise.resolve(fakeComponent));
+    const wrapper = mount(<LazyComponent text="test" />);
+
+    // Initially shows fallback
+    assert.isTrue(wrapper.exists('[data-testid="fallback"]'));
+    assert.isFalse(wrapper.exists('[data-testid="loaded-component"]'));
+
+    // Wait for component to load
+    await delay(0);
+    wrapper.update();
+
+    // Now shows loaded component
+    assert.isFalse(wrapper.exists('[data-testid="fallback"]'));
+    assert.isTrue(wrapper.exists('[data-testid="loaded-component"]'));
+    assert.equal(
+      wrapper.find('[data-testid="loaded-component"]').text(),
+      'test',
+    );
+  });
+
+  it('passes props to loaded component', async () => {
+    fakeLoader.returns(Promise.resolve(fakeComponent));
+    const wrapper = mount(<LazyComponent text="test" customProp="value" />);
+
+    await delay(0);
+    wrapper.update();
+
+    const loadedComponent = wrapper.find('[data-testid="loaded-component"]');
+    assert.equal(loadedComponent.text(), 'test');
+    // The component should receive all props passed to the lazy wrapper
+    assert.equal(loadedComponent.parent().prop('customProp'), 'value');
+  });
+
+  it('renders error fallback when loading fails', async () => {
+    const error = new Error('Loading failed');
+    fakeLoader.returns(Promise.reject(error));
+    const wrapper = mount(<LazyComponent text="test" />);
+
+    // Initially shows fallback
+    assert.isTrue(wrapper.exists('[data-testid="fallback"]'));
+
+    // Wait for loading to fail
+    await delay(0);
+    wrapper.update();
+
+    // Now shows error fallback
+    assert.isFalse(wrapper.exists('[data-testid="fallback"]'));
+    assert.isTrue(wrapper.exists('[data-testid="error-fallback"]'));
+    assert.equal(
+      wrapper.find('[data-testid="error-fallback"]').text(),
+      'test - Error: Loading failed',
+    );
+  });
+
+  it('renders default error fallback when `errorFallback` is not provided', async () => {
+    const error = new Error('Loading failed');
+    fakeLoader.returns(Promise.reject(error));
+
+    const LazyComponentWithoutErrorFallback = lazy(
+      'TestComponent',
+      fakeLoader,
+      {
+        fallback: ({ text }) => <div data-testid="fallback">{text}</div>,
+      },
+    );
+
+    const wrapper = mount(<LazyComponentWithoutErrorFallback text="test" />);
+
+    // Wait for loading to fail
+    await delay(0);
+    wrapper.update();
+
+    assert.isTrue(
+      wrapper.text().includes('There was a problem loading this content'),
+    );
+    assert.isTrue(wrapper.text().includes('Loading failed'));
+  });
+
+  it('does not call loader again if re-rendered while loading', async () => {
+    fakeLoader.returns(Promise.resolve(fakeComponent));
+    const wrapper = mount(<LazyComponent text="test" />);
+
+    // Re-render component before loader result has been processed.
+    wrapper.setProps({ text: 'updated' });
+
+    assert.calledOnce(fakeLoader);
+  });
+
+  it('sets displayName on the returned component', () => {
+    assert.equal(LazyComponent.displayName, 'Lazy(TestComponent)');
+  });
+});