feat: use `@lit/task` to schedule async data fetching #2912

gavinbarron · 2023-12-13T00:42:40Z

PR Type

Bugfix
Feature

Description of the changes

This PR introduces a new approach to loading component state via async calls.
The approach provided in the MgtBaseComponent and MgtTemplatedComponent relied on manually calling the requestUpdate method and exposing a requestStateUpdate method to manually load external state via an http call.
This had a side effect of scheduling updates during an update cycle which is inefficient and results in a warning emitted to the console when running in developer mode.

The new approach introduces two replacement base classes MgtBaseTaskComponent and MgtTemplatedTaskComponent which should be used to replace their respective predecessors.

@lit/task is used to wrap up the existing loadState method in each component, this is supplied by MgtBaseTaskComponent. Implementing classes must implement:

args: () => unknown[] instance method. The array returned should contain all of the reactive properties on the object which when changed will trigger loadState method to be called. This array should contain the providerState property from the base class.
renderContent: () => TemplateResult the existing render method should be renamed to this. The implementation of the render method is provided by each of the base classes and provides default implementations for rendering while the task execution is in progress and if an error occurs. You may of course provide component specific overrides for any of these methods as needed.
@property decorators on fields with custom accessor methods should be moved to decorate the setter method rather than the getter as was done previously. If a field is calling requestStateUpdate then it should be present in the array returned from the args method
JSDoc comments MUST be left on the getters to ensure that code generation for the React wrapper library is left intact.

The existing base classes will be marked as @deprected when the migration is complete and may be removed in a future version.

Testing of these changes needs to be done locally, The react-contoso application is a good test bed, however it's important to try navigating away and back to a page with the component being tested as sometimes the warning doesn't occur on a full page reload.

As this is a large change I'd recommend reviewing the changes by looking at each commit as a change to help with chunking this. after the initial commits getting the pattern set I've kept the changes in a single commit to cover a single component or set of related components.

PR checklist

Project builds (yarn build) and changes have been tested in at least two supported browsers (Edge + non-Chromium based browser)
All public APIs (classes, methods, etc) have been documented following the jsdoc syntax
Stories have been added and existing stories have been tested
Added appropriate documentation. Docs PR:

License header has been added to all new source files (yarn setLicense)
Contains NO breaking changes