@servicetitan/docs-uikit 30.0.0 → 30.1.1

package/docs/web-components/event-bus.mdx

@@ -0,0 +1,515 @@
+---
+title: EventBus
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+Use EventBus to exchange messages (aka events) between a host and MFEs, or between concurrently mounted MFEs.
+
+### Providing EventBus
+
+To use EventBus, provide an instance via `EVENT_BUS_TOKEN`.
+[Loader](#loader) automatically passes the EventBus through to MFEs.
+For example,
+
+```tsx
+import { Provider } from '@servicetitan/react-ioc';
+import { EVENT_BUS_TOKEN, EventBus } from '@servicetitan/web-components';
+
+export const App = () => {
+    return (
+        <Provider singletons={[{ provide: EVENT_BUS_TOKEN, useValue: new EventBus() }]}>
+            {/* EVENT_BUS_TOKEN is automatically provided in MFEs */}
+        </Provider>
+    );
+};
+```
+
+### Naming events
+
+EventBus is a shared resource that can be used simultaneously by independently
+developed modules and MFEs and it is important to avoid generic event names
+that could be mistakenly handled by the wrong recipient.
+
+To avoid name collisions, prefix events names with the name of the module that
+owns them; that could be the module that sends the events, or the module that handles them.
+
+The recommended format is `{module}:{name}`, for example **"fleet-mfe:refresh-token"** and **"navigation:tooltip"**.
+
+### Sending events
+
+To send an event, call [emit](#emit) with the event name.
+
+The event is delivered to all active listeners regardless whether it originated within the host or an MFE.
+
+For example, this component sends a **"example:click"** when the user clicks a button.
+
+```tsx
+import { Button } from '@servicetitan/anvil2';
+import { useDependencies } from '@servicetitan/react-ioc';
+import { EVENT_BUS_TOKEN } from '@servicetitan/web-components';
+import { useCallback } from 'react';
+
+function EventSender() {
+    const [eventBus] = useDependencies(EVENT_BUS_TOKEN);
+
+    const handleClick = useCallback(() => eventBus.emit('example:click'), [eventBus]);
+
+    return <Button onClick={handleClick}>Click Here</Button>;
+}
+```
+
+### Handling events
+
+To handle an event, call [on](#on) to register a handler that is called when the event occurs, and call [off](#off) to remove the handler.
+
+All active handlers are called when the event occurs, regardless whether the handler is in the host or an MFE.
+
+For example, this component renders the date and time when the **"example:click"** last occurred:
+
+```tsx
+import { useDependencies } from '@servicetitan/react-ioc';
+import { EVENT_BUS_TOKEN } from '@servicetitan/web-components';
+import { useCallback, useEffect, useState } from 'react';
+
+function EventHandler() {
+    const [eventBus] = useDependencies(EVENT_BUS_TOKEN);
+    const [lastOccurredAt, setLastOccurredAt] = useState<Date>();
+
+    const handleClickEvent = useCallback(() => setLastOccurredAt(new Date()), []);
+
+    useEffect(() => {
+        eventBus.on('example:click', handleClickEvent);
+        return () => {
+            eventBus.off('example:click', handleClickEvent);
+        };
+    }, [eventBus, handleClickEvent]);
+
+    return lastOccurredAt ? `Click last occurred at: ${lastOccurredAt.toISOString()}` : null;
+}
+```
+
+### Sending data with events
+
+To send data with an event, call [emit](#emit) with the data to send.
+
+This example sends an **"example:input"** with the value entered into an input field.
+It also illustrates how to ensure event data is correctly typed (see [typedEventBusToken](#typedeventbustoken)).
+
+<Tabs
+    defaultValue="sender"
+    values={[
+        { label: 'Sender', value: 'sender' },
+        { label: 'Handler', value: 'handler' },
+        { label: 'Types', value: 'types' },
+    ]}
+>
+<TabItem value="types">
+
+```tsx
+import { EventBus, typedEventBusToken } from '@servicetitan/web-components';
+
+export enum Events {
+    input = 'example:input',
+}
+
+export interface ExampleEvents {
+    [Events.input]: { value: string };
+}
+
+export type ExampleEventBus = EventBus<ExampleEvents>;
+
+export const EXAMPLE_EVENT_BUS_TOKEN = typedEventBusToken<ExampleEvents>();
+```
+
+</TabItem>
+<TabItem value="sender">
+
+```tsx
+import { TextField } from '@servicetitan/anvil2';
+import { useDependencies } from '@servicetitan/react-ioc';
+import { useEffect, useState } from 'react';
+
+import { Events, EXAMPLE_EVENT_BUS_TOKEN } from './types';
+
+function EventSender() {
+    const [eventBus] = useDependencies(EXAMPLE_EVENT_BUS_TOKEN);
+    const [input, setInput] = useState('');
+
+    useEffect(() => eventBus.emit(Events.input, { value: input }), [eventBus, input]);
+
+    return (
+        <TextField
+            label="Enter value:"
+            value={input}
+            onChange={event => setInput(event.target.value)}
+        />
+    );
+}
+```
+
+</TabItem>
+<TabItem value="handler">
+
+```tsx
+import { useDependencies } from '@servicetitan/react-ioc';
+import { useEffect, useState } from 'react';
+
+import { Events, ExampleEvents, EXAMPLE_EVENT_BUS_TOKEN } from './types';
+
+function EventHandler() {
+    const [eventBus] = useDependencies(EXAMPLE_EVENT_BUS_TOKEN);
+    const [data, setData] = useState<ExampleEvents[Events.input]>();
+
+    useEffect(() => {
+        eventBus.on(Events.input, setData);
+        return () => {
+            eventBus.off(Events.input, setData);
+        };
+    }, [eventBus]);
+
+    return data ? `Received: "${data.value}"` : null;
+}
+```
+
+</TabItem>
+</Tabs>
+
+### Returning results from handlers
+
+EventBus provides a separate "jobs" API for when you want to wait for an event to be handled.
+
+:::caution
+The jobs API assumes there is only one handler for each job event.
+If there are multiple handlers, only the first result is returned.
+:::
+
+This example runs a job that randomly succeeds of fails, then displays the result.
+
+<Tabs
+    defaultValue="sender"
+    values={[
+        { label: 'Sender', value: 'sender' },
+        { label: 'Handler', value: 'handler' },
+        { label: 'Types', value: 'types' },
+    ]}
+>
+<TabItem value="types">
+
+```tsx
+import { symbolToken } from '@servicetitan/react-ioc';
+
+export interface JobResult {
+    data: number;
+}
+
+export const JOB_EVENT = symbolToken<JobResult>('example:job');
+```
+
+</TabItem>
+<TabItem value="sender">
+
+```tsx
+import { Button, Text } from '@servicetitan/anvil2';
+import { useDependencies } from '@servicetitan/react-ioc';
+import { EVENT_BUS_TOKEN } from '@servicetitan/web-components';
+import { useCallback, useState, Fragment } from 'react';
+
+import { JOB_EVENT } from './types';
+
+function JobRunner() {
+    const [eventBus] = useDependencies(EVENT_BUS_TOKEN);
+    const [result, setResult] = useState<{ data?: number; error?: string }>();
+
+    const handleRunJob = useCallback(async () => {
+        setResult(undefined);
+        try {
+            // Send job event and wait for result
+            const { data } = await eventBus.job.emit(JOB_EVENT);
+            setResult({ data });
+        } catch (error) {
+            if (typeof error === 'string') {
+                setResult({ error });
+            }
+        }
+    }, [eventBus]);
+
+    return (
+        <Fragment>
+            <Button onClick={handleRunJob}>Run Job</Button>
+            {result && <Text variant="body">{result.data ?? result.error}</Text>}
+        </Fragment>
+    );
+}
+```
+
+</TabItem>
+<TabItem value="handler">
+
+```ts
+import { useDependencies } from '@servicetitan/react-ioc';
+import { EVENT_BUS_TOKEN, JobEventHandler } from '@servicetitan/web-components';
+import { useCallback, useEffect } from 'react';
+
+import { JOB_EVENT, JobResult } from './types';
+
+function JobHandler() {
+    const [eventBus] = useDependencies(EVENT_BUS_TOKEN);
+
+    /**
+     * Job handlers can resolve with a result, or reject with an error.
+     * This handler generates a random number from 0 thru 10 and rejects if the number is <5.
+     */
+
+    const handleJob = useCallback<JobEventHandler<JobResult>>(({ resolve, reject }) => {
+        const getValue = () => Math.round(10 * Math.random());
+
+        setTimeout(() => {
+            const value = getValue();
+            if (value >= 5) {
+                resolve({ data: value });
+            } else {
+                reject(`Error: value is ${value}`);
+            }
+        }, 2000);
+    }, []);
+
+    useEffect(() => {
+        eventBus.job.on(JOB_EVENT, handleJob); // Register job handler
+        return () => {
+            eventBus.job.off(JOB_EVENT, handleJob); // Remove job handler
+        };
+    }, [eventBus, handleJob]);
+
+    return null;
+}
+```
+
+</TabItem>
+</Tabs>
+
+## API
+
+### emit
+
+Sends an event, with optional data.
+
+```ts
+emit(event: string | symbol | number, data: JSON | JSONPrimitive)
+```
+
+#### Parameters
+
+| Name    | Type                         | Description                                   |
+| :------ | :--------------------------- | :-------------------------------------------- |
+| `event` | `string \| symbol \| number` | The event to send.                            |
+| `data`  | `JSON \| JSONPrimitive`      | Optional data to pass to the event's handler. |
+
+#### Event data
+
+Event data must serializable, meaning it must be a primitive type (i.e., `string | number | boolean | null`) or objects or arrays containing only primitive types.
+Specifically:
+
+```tsx
+export type JSONPrimitive = string | number | boolean | null | undefined;
+export type JSON = { [key: string]: JSONPrimitive | JSON[] | JSON };
+```
+
+#### Usage
+
+If the EventBus is not typed (see [typedEventBusToken](#typedeventbustoken)), `event` and `data` are not restricted.
+
+Otherwise, `event` must be one of the declared events and `data` must match the declared event's type.
+For example,
+
+```ts
+import { EventBus } from '@servicetitan/web-components';
+
+interface ExampleEvents {
+    'example:click': undefined;
+    'example:input': string;
+}
+
+function test(eventBus: EventBus<ExampleEvents>) {
+    // Note: eventBus is typed EventBus<ExampleEvents>
+
+    eventBus.emit('example:click'); // OK
+    eventBus.emit('example:click', 'something'); // ERROR: Argument of type 'string' is not assignable to parameter of type 'undefined'.
+
+    eventBus.emit('example:input', 'something'); // OK
+    eventBus.emit('example:input'); // ERROR: Expected 2 arguments, but got 1
+    eventBus.emit('example:input', 42); // ERROR: Argument of type 'number' is not assignable to parameter of type 'string'
+
+    eventBus.emit('other-event'); // ERROR: Argument of type '"other-event"' is not assignable to parameter of type 'keyof ExampleEvents | SymbolToken<any>'.
+}
+```
+
+### on
+
+Registers an event handler.
+
+```ts
+on(event: string | symbol | number, handler: (data?: JSON | JSONPrimitive) => void)
+```
+
+#### Parameters
+
+| Name      | Type                                     | Description                                |
+| :-------- | :--------------------------------------- | :----------------------------------------- |
+| `event`   | `string \| symbol \| number`             | The event to handle.                       |
+| `handler` | `(data?: JSON \| JSONPrimitive) => void` | The handler to call when the event occurs. |
+
+If the EventBus is not typed (see [typedEventBusToken](#typedeventbustoken)), `event` and `data` are not restricted.
+
+Otherwise, `event` must be one of the declared events and `data` must match the declared event's type.
+For example,
+
+```ts
+import { EventBus } from '@servicetitan/web-components';
+
+interface ExampleEvents {
+    'example:click': undefined;
+    'example:input': string;
+}
+
+function test(eventBus: EventBus<ExampleEvents>) {
+    // Note: eventBus is typed EventBus<ExampleEvents>
+
+    eventBus.on('example:click', () => {}); // OK
+    eventBus.on('example:click', (_value: string) => {}); // ERROR: Type 'undefined' is not assignable to type 'string'
+
+    eventBus.on('example:input', () => {}); // OK
+    eventBus.on('example:input', (_value: string) => {}); // OK
+    eventBus.on('example:input', (_value: number) => {}); // ERROR: Type 'string' is not assignable to type 'number'
+
+    eventBus.on('other-event', () => {}); // ERROR: Argument of type '"other-event"' is not assignable to parameter of type 'SymbolToken<any> | keyof ExampleEvents'.
+}
+```
+
+### off
+
+Deregisters an event handler.
+
+```ts
+off(event: string | symbol  number, handler: (data?: JSON | JSONPrimitive) => void)
+```
+
+#### Parameters
+
+| Name      | Type                                     | Description                        |
+| :-------- | :--------------------------------------- | :--------------------------------- |
+| `event`   | `string \| symbol \| number`             | The previously registered event.   |
+| `handler` | `(data?: JSON \| JSONPrimitive) => void` | The previously registered handler. |
+
+### job.emit
+
+Sends a "job" event and returns the result, or an error.
+
+```ts
+job.emit(event: symbolToken<T>): Promise<T>
+```
+
+#### Parameters
+
+| Name    | Type             | Description                                                                                                               |
+| :------ | :--------------- | :------------------------------------------------------------------------------------------------------------------------ |
+| `event` | `symbolToken<T>` | The event to send. Use a [symbolToken](#symboltoken) to ensure that senders and handlers agree on the job's return value. |
+
+#### Returns
+
+Returns a Promise that resolves with the handler's result, or rejects with an error.
+
+### job.on
+
+Registers a "job" event handler.
+
+```ts
+job.on(event: symbolToken<T>, handler: JobEventHandler<T>);
+```
+
+#### Parameters
+
+| Name      | Type                 | Description                                                                                                                                                                                                          |
+| :-------- | :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `event`   | `symbolToken<T>`     | The event to send. Use a [symbolToken](#symboltoken) to ensure that senders and handlers agree on the job's return value.                                                                                            |
+| `handler` | `JobEventHandler<T>` | The handler to call when the event occurs, where `T` is the jobs's return value.<br />The handler is passed `resolve` and `reject` callbacks. Call `resolve` to return the result. Call `reject` to return an error. |
+
+### job.off
+
+Deregisters a "job" event handler.
+
+#### Parameters
+
+| Name      | Type                 | Description                        |
+| :-------- | :------------------- | :--------------------------------- |
+| `event`   | `symbolToken<T>`     | The previously registered event.   |
+| `handler` | `JobEventHandler<T>` | The previously registered handler. |
+
+### typedEventBusToken
+
+Use `typedEventBusToken` to specialize the generic `EventBus` type so that [emit](#emit), [on](#on) and [off](#off) only allow specific events.
+
+```ts
+function typedEventBusToken<T>(): SymbolToken<T>;
+```
+
+It returns an `EVENT_BUS_TOKEN` that resolves to the specified type of EventBus.
+
+#### Examples
+
+This example declares a `CustomEventBus` that only
+allows **"example:click"** and **"example:input"**, and that requires **"example:input"** to be sent with a string value.
+
+`typedEventBusToken` returns a convenient shorthand for using `CustomEventBus`.
+
+```ts
+import { useDependencies } from '@servicetitan/react-ioc';
+import { EVENT_BUS_TOKEN, typedEventBusToken } from '@servicetitan/web-components';
+
+interface CustomEvents {
+    'example:click': undefined;
+    'example:input': string;
+}
+
+const CUSTOM_EVENT_BUS_TOKEN = typedEventBusToken<CustomEvents>();
+
+function Test() {
+    // eventBus is not typed: emit() and on() allow any events and data
+    const [eventBus] = useDependencies(EVENT_BUS_TOKEN);
+
+    /**
+     * customEventBus is typed: emit() and on() allow only keys of CustomEvents and matching data
+     * Using CUSTOM_EVENT_BUS_TOKEN is equivalent to:
+     *   useDependencies(EVENT_BUS_TOKEN as SymbolToken<CustomEventBus>)
+     */
+    const [customEventBus] = useDependencies(CUSTOM_EVENT_BUS_TOKEN);
+}
+```
+
+### symbolToken
+
+`symbolToken` creates a JavaScript symbol that is tightly associated with a type.
+
+```ts
+function symbolToken<T>(name: string): symbol;
+```
+
+It allows the EventBus APIs to infer from events the types of their data and results.
+
+#### Job events
+
+For example, to define the result of a job event:
+
+```ts
+import { symbolToken } from '@servicetitan/react-ioc';
+import { EventBus } from '@servicetitan/web-components';
+
+// Create JOB_EVENT symbol with type { data: string }
+const JOB_EVENT = symbolToken<{ data: string }>('JOB_EVENT');
+
+async function test(eventBus: EventBus) {
+    // And then job.emit(JOB_EVENT) infers the return type is { data: string }
+    const result = await eventBus.job.emit(JOB_EVENT);
+}
+```

package/docs/{web-components.mdx → web-components/web-components.mdx}

@@ -1,285 +1,230 @@
----
-title: Web Components
----
-
-#### [CHANGELOG (@servicetitan/web-components)](https://github.com/servicetitan/uikit/blob/master/packages/web-components/CHANGELOG.md)
-
-`@servicetitan/web-components` is used to build, register, and load Microfrontends (MFEs) into host applications.
-
-### Loader
-
-The `Loader` component is used to load an MFE into a host application. See [Microfrontends (MFEs)](/docs/frontend/micro-frontends) for more information about how MFEs are injected.
-
-#### Usage
-
-```tsx
-...
-
-import { Loader } from '@servicetitan/web-components';
-
-...
-
-export const Foo: React.FC = () => {
-    ...
-    return (
-        ...
-        <Loader src="https://unpkg.servicetitan.com/{package_name}@{semver_range}" />
-        ...
-    );
-};
-```
-
-#### Props
-
-| Name                     | Description                                                                                                                                         |
-| :----------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `src`                    | path to an MFE root folder                                                                                                                          |
-| `fallbackSrc`            | optional alternative path to an MFE root folder (if request for src returns error)                                                                  |
-| `data`                   | additional data passed to an MFE as an object, where values are serializable, and preferably memoized ([see below](#passing-data-from-host-to-mfe)) |
-| `basename`               | prefix for all MFE URLs, you should inject it by the `BASENAME_TOKEN` and pass to the appropriate router property                                   |
-| `loadingFallback`        | optional ReactNode to render when the MFE is loading                                                                                                |
-| `loadingFallbackDelayed` | controls whether to render the loading fallback immediately, or after a short delay [(see below)](#fallback-delay)                                  |
-| `errorFallback`          | optional ReactNode to render when the MFE fails to load                                                                                             |
-| `className`              | additional CSS classes for the MFE web component element                                                                                            |
-| `cache`                  | optional cache strategy for the MFE [(see below)](#cache-strategy)                                                                                  |
-
-#### Loading fallback delay {#fallback-delay}
-
-To prevent the loading fallback from flickering on then off when an MFE loads quickly, `Loader` does not render the fallback immediately. It waits a moment (currently 200ms) then renders the fallback only if the MFE hasn't finished loading. Set `loadingFallbackDelayed` to `false` to always render the fallback, regardless how quickly the MFE loads.
-
-#### Cache strategy {#cache-strategy}
-
-When an MFE is loaded, `Loader` fetches the version and bundle data from the `src` (or `fallbackSrc`) endpoint and stores the information in a cache. Then, if the MFE is unloaded and subsequently reloaded, it reuses the cached information. Use `cache` to control whether or how long `Loader` caches an MFE's data:
-
-- `true`: cache the data for the standard interval (currently 15 minutes). This is the default value.
-- `false`: do not cache the data; (re)fetch it every time the MFE is loaded
-- `-1`: cache the data indefinitely (i.e., for the duration of the user's session)
-- _&lt;number&gt;_: cache the data for the specified _&lt;number&gt;_ of milliseconds
-
-#### Passing data from Host to MFE
-
-Use `data` to pass data from your host application to the MFE. The data should be an object where keys are strings and the values are any serializable data.
-
-To avoid performance issues with re-rendering and re-serializing the value, we recommend memoizing the `data` object passed to `<Loader>`.
-
-**Reminder:** Don't casually share data between the host and MFEs. When possible, MFEs should load the data they need instead of relying on the host to pass it.
-
-:::note
-Before version v22.12.0 of `@servicetitan/web-components` package, the `data` prop only supported data of type `Record<string, string>`
-:::
-
-```tsx title="Host Application"
-import { useMemo } from 'react';
-import { Loader } from '@servicetitan/web-components';
-...
-export const HostApp = () => {
-    ...
-    const data = useMemo(() => {
-        foo: ['one', 'two', 'three'],
-        bar: dependency,
-    }, [dependency]);
-    return (
-        ...
-        <Loader
-            src="https://unpkg.servicetitan.com/{package_name}@{semver_range}"
-            data={data}
-        />
-        ...
-    );
-};
-```
-
-Data can be accessed within the MFE using props.
-
-```tsx title="MFE Application"
-interface MFEAppData {
-    foo: string[];
-}
-
-export const MFEApp = (props: MFEAppData) => {
-    const { foo } = props;
-};
-```
-
-Data must be serializable, due to the nature of how it is passed through a web component to reach your MFE component. This means that you cannot pass functions or other non-serializable data types.
-
-```tsx title="Host Application"
-...
-<Loader data={{ date: new Date("2020-05-12T23:50:21.817Z") }} />
-```
-
-```tsx title="MFE Application"
-...
-export const MFEApp = (props: MyType) => {
-    props.date; // '2020-05-12T23:50:21.817Z'
-};
-// RESULTS IN A STRING, NOT A DATE OBJECT
-```
-
-As of version v22.12.0 of `@servicetitan/web-components`, if data passed into the `data` prop of `<Loader>` changes during runtime, the data will re-render within your MFE component where appropriate. Previous versions would re-mounting the entire MFE application when data changed.
-
-### useMFEDataContext
-
-Data can be also be accessed within the MFE using the `useMFEDataContext` hook. You must provide the type of the data you expect to recieve.
-
-```tsx
-import { useMFEDataContext } from '@servicetitan/web-components';
-...
-interface MFEAppData {
-    bar: string;
-}
-
-export const MFEApp = () => {
-    const { bar } = useMFEDataContext<MFEAppData>();
-};
-```
-
-### useMFEMetadataContext
-
-Some metadata is also provided to MFEs, and is accessible through the `useMFEMetadataContext` hook.
-
-```tsx
-import { useMFEMetadataContext } from '@servicetitan/web-components';
-...
-export const MFEApp = () => {
-    const { shadowRoot, portalShadowRoot } = useMFEMetadataContext();
-};
-```
-
-The following metadata about an MFE is available from `useMFEMetadataContext` hook.
-
-| Name               | Type       | Description                                                                                                                     |
-| :----------------- | :--------- | :------------------------------------------------------------------------------------------------------------------------------ |
-| `shadowRoot`       | ShadowRoot | ShadowRoot root node of which the MFE is rendered within                                                                        |
-| `portalShadowRoot` | ShadowRoot | ShadowRoot root node of the "portal" tied to the MFE, which is used to render elements in a div directly under the body element |
-
-### getValueForEnvironment
-
-`getValueForEnvironment` detects the host environment and returns a corresponding value.
-
-:::caution
-When no value is provided for the detected environment, `getValueForEnvironment` returns `undefined`.
-:::
-
-#### Props
-
-| Name                 | Type                     | Description                                                                                                               |
-| :------------------- | :----------------------- | :------------------------------------------------------------------------------------------------------------------------ |
-| `values`             | `Record<string, string>` | Object that maps each environment to a value (see below).                                                                 |
-| `defaultEnvironment` | `keyof typeof values`    | The environment to use when the current environment is not recognized or is not included in `values`. Defaults to `"qa"`. |
-| `hostname`           | `string`                 | The hostname of the current environment. Defaults to `window.location.hostname`                                           |
-
-The recognized environments are:
-
-| Environment       | Description                                                        |
-| :---------------- | :----------------------------------------------------------------- |
-| **dev**           | Development environment (i.e., `localhost`, `127.0.0.1`)           |
-| **go**            | Production environment                                             |
-| **qa**            | QA environment                                                     |
-| **next**          | Next environment                                                   |
-| **stage**         | Staging environment                                                |
-| **test**          | Unit test environment (i.e., `process.env.NODE_ENV === 'test'`)    |
-| `<string>`        | Custom environment that matches against`<string>.servicetitan.com` |
-| `<string>.st.dev` | Custom environment that matches against `<string>.st.dev`          |
-
-#### Custom environments
-
-Custom environments are for applications and services that run separately from the Monolith.
-For example, to associate **prod** with `my-service.servicetitan.com` and **stage** with `my-service-stage.st.dev`:
-
-```json
-{
-    "my-service": "prod", // Matches my-service.servicetitan.com
-    "stage.st.dev": "stage" // Matches *stage.st.dev
-}
-```
-
-#### Examples
-
-Determine LaunchDarkly client-side ID for TitanAdvisor project.
-
-```tsx
-function useTitanAdvisorClientSideID() {
-    return useMemo(() => {
-        return getValueForEnvironment({
-            dev: '669fe6e5cc97eb103be7a620',
-            go: '669fe5bff00a0c0fa60b25e4',
-            next: '669fe5bff00a0c0fa60b25e4', // same a 'go' but could also be 'qa'
-            qa: '669fe6d6f00a0c0fa60b2721',
-            stage: '669fe65979abf310b860236e',
-        });
-    }, []);
-}
-```
-
-:::info
-Note that because the environment is fixed for the life the application, it is safe to memoize the return value.
-:::
-
-:::caution
-Do not call `getValueForEnvironment` globally, outside a React component or hook. That usage assumes that all the information needed to determine the environment is available immediately when the Javascript runtime loads and before the application is initialized. While that might work it might also change in the future.
-:::
-
-### EVENT_BUS_TOKEN - Emitting Events to MFEs
-
-Sometimes you may need to send events from the host to the MFE or the other way around, the EventBus ([mitt](https://github.com/developit/mitt) is used under the hood) should cover these needs. Starting <code>v22.1.0</code> you can also send payload.
-
-#### Subscription
-
-```tsx title="MFE"
-...
-
-import { useOptionalDependencies } from '@servicetitan/react-ioc';
-import { EVENT_BUS_TOKEN } from '@servicetitan/web-components';
-
-...
-
-export const Foo: FC = () => {
-    const [eventBus] = useOptionalDependencies(EVENT_BUS_TOKEN);
-
-    useEffect(() => {
-        const myCustomEventHandler = () => {
-            console.log('`my-custom-event` has been fired!');
-        };
-        eventBus?.on('my-custom-event', myCustomEventHandler);
-
-        return () => {
-            eventBus?.off('my-custom-event', myCustomEventHandler);
-        };
-    }, []);
-
-    ...
-};
-```
-
-#### Emitting
-
-```tsx title="host"
-...
-
-import { Loader, LoaderRef } from '@servicetitan/web-components';
-
-...
-
-export const Bar: FC = () => {
-    const ref = useRef<LoaderRef>(null);
-
-    useEffect(() => {
-        const id = setInterval(() => {
-            ref.current?.emit('my-custom-event');
-        }, 1000);
-
-        return () => {
-            clearInterval(id);
-        };
-    }, []);
-
-    ...
-
-    return (
-        ...
-        <Loader ref={ref} src="https://unpkg.servicetitan.com/@servicetitan/examples" />
-        ...
-    );
-};
-```
+---
+title: Web Components
+---
+
+#### [CHANGELOG (@servicetitan/web-components)](https://github.com/servicetitan/uikit/blob/master/packages/web-components/CHANGELOG.md)
+
+`@servicetitan/web-components` is used to build, register, and load Microfrontends (MFEs) into host applications.
+
+## Loader
+
+The `Loader` component is used to load an MFE into a host application. See [Microfrontends (MFEs)](/docs/frontend/micro-frontends) for more information about how MFEs are injected.
+
+### Usage
+
+```tsx
+...
+
+import { Loader } from '@servicetitan/web-components';
+
+...
+
+export const Foo: React.FC = () => {
+    ...
+    return (
+        ...
+        <Loader src="https://unpkg.servicetitan.com/{package_name}@{semver_range}" />
+        ...
+    );
+};
+```
+
+### Props
+
+| Name                     | Description                                                                                                                                         |
+| :----------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src`                    | path to an MFE root folder                                                                                                                          |
+| `fallbackSrc`            | optional alternative path to an MFE root folder (if request for src returns error)                                                                  |
+| `data`                   | additional data passed to an MFE as an object, where values are serializable, and preferably memoized ([see below](#passing-data-from-host-to-mfe)) |
+| `basename`               | prefix for all MFE URLs, you should inject it by the `BASENAME_TOKEN` and pass to the appropriate router property                                   |
+| `loadingFallback`        | optional ReactNode to render when the MFE is loading                                                                                                |
+| `loadingFallbackDelayed` | controls whether to render the loading fallback immediately, or after a short delay [(see below)](#fallback-delay)                                  |
+| `errorFallback`          | optional ReactNode to render when the MFE fails to load                                                                                             |
+| `className`              | additional CSS classes for the MFE web component element                                                                                            |
+| `cache`                  | optional cache strategy for the MFE [(see below)](#cache-strategy)                                                                                  |
+
+### Loading fallback delay {#fallback-delay}
+
+To prevent the loading fallback from flickering on then off when an MFE loads quickly, `Loader` does not render the fallback immediately. It waits a moment (currently 200ms) then renders the fallback only if the MFE hasn't finished loading. Set `loadingFallbackDelayed` to `false` to always render the fallback, regardless how quickly the MFE loads.
+
+### Cache strategy {#cache-strategy}
+
+When an MFE is loaded, `Loader` fetches the version and bundle data from the `src` (or `fallbackSrc`) endpoint and stores the information in a cache. Then, if the MFE is unloaded and subsequently reloaded, it reuses the cached information. Use `cache` to control whether or how long `Loader` caches an MFE's data:
+
+- `true`: cache the data for the standard interval (currently 15 minutes). This is the default value.
+- `false`: do not cache the data; (re)fetch it every time the MFE is loaded
+- `-1`: cache the data indefinitely (i.e., for the duration of the user's session)
+- _&lt;number&gt;_: cache the data for the specified _&lt;number&gt;_ of milliseconds
+
+### Passing data from Host to MFE
+
+Use `data` to pass data from your host application to the MFE. The data should be an object where keys are strings and the values are any serializable data.
+
+To avoid performance issues with re-rendering and re-serializing the value, we recommend memoizing the `data` object passed to `<Loader>`.
+
+**Reminder:** Don't casually share data between the host and MFEs. When possible, MFEs should load the data they need instead of relying on the host to pass it.
+
+:::note
+Before version v22.12.0 of `@servicetitan/web-components` package, the `data` prop only supported data of type `Record<string, string>`
+:::
+
+```tsx title="Host Application"
+import { useMemo } from 'react';
+import { Loader } from '@servicetitan/web-components';
+...
+export const HostApp = () => {
+    ...
+    const data = useMemo(() => {
+        foo: ['one', 'two', 'three'],
+        bar: dependency,
+    }, [dependency]);
+    return (
+        ...
+        <Loader
+            src="https://unpkg.servicetitan.com/{package_name}@{semver_range}"
+            data={data}
+        />
+        ...
+    );
+};
+```
+
+Data can be accessed within the MFE using props.
+
+```tsx title="MFE Application"
+interface MFEAppData {
+    foo: string[];
+}
+
+export const MFEApp = (props: MFEAppData) => {
+    const { foo } = props;
+};
+```
+
+Data must be serializable, due to the nature of how it is passed through a web component to reach your MFE component. This means that you cannot pass functions or other non-serializable data types.
+
+```tsx title="Host Application"
+...
+<Loader data={{ date: new Date("2020-05-12T23:50:21.817Z") }} />
+```
+
+```tsx title="MFE Application"
+...
+export const MFEApp = (props: MyType) => {
+    props.date; // '2020-05-12T23:50:21.817Z'
+};
+// RESULTS IN A STRING, NOT A DATE OBJECT
+```
+
+As of version v22.12.0 of `@servicetitan/web-components`, if data passed into the `data` prop of `<Loader>` changes during runtime, the data will re-render within your MFE component where appropriate. Previous versions would re-mounting the entire MFE application when data changed.
+
+## useMFEDataContext
+
+Data can be also be accessed within the MFE using the `useMFEDataContext` hook. You must provide the type of the data you expect to receive.
+
+```tsx
+import { useMFEDataContext } from '@servicetitan/web-components';
+...
+interface MFEAppData {
+    bar: string;
+}
+
+export const MFEApp = () => {
+    const { bar } = useMFEDataContext<MFEAppData>();
+};
+```
+
+## useMFEMetadataContext
+
+Some metadata is also provided to MFEs, and is accessible through the `useMFEMetadataContext` hook.
+
+```tsx
+import { useMFEMetadataContext } from '@servicetitan/web-components';
+...
+export const MFEApp = () => {
+    const { shadowRoot, portalShadowRoot } = useMFEMetadataContext();
+};
+```
+
+The following metadata about an MFE is available from `useMFEMetadataContext` hook.
+
+| Name               | Type       | Description                                                                                                                     |
+| :----------------- | :--------- | :------------------------------------------------------------------------------------------------------------------------------ |
+| `shadowRoot`       | ShadowRoot | ShadowRoot root node of which the MFE is rendered within                                                                        |
+| `portalShadowRoot` | ShadowRoot | ShadowRoot root node of the "portal" tied to the MFE, which is used to render elements in a div directly under the body element |
+
+## getValueForEnvironment
+
+`getValueForEnvironment` detects the host environment and returns a corresponding value.
+
+```ts
+function getValueForEnvironment(
+    values: Record<string, string>,
+    defaultEnvironment: keyof typeof values = 'qa',
+    hostname: string = window.location.hostname
+);
+```
+
+:::caution
+When no value is provided for the detected environment, `getValueForEnvironment` returns `undefined`.
+:::
+
+### Parameters
+
+| Name                 | Type                     | Description                                                                                                               |
+| :------------------- | :----------------------- | :------------------------------------------------------------------------------------------------------------------------ |
+| `values`             | `Record<string, string>` | Object that maps each environment to a value (see below).                                                                 |
+| `defaultEnvironment` | `keyof typeof values`    | The environment to use when the current environment is not recognized or is not included in `values`. Defaults to `"qa"`. |
+| `hostname`           | `string`                 | The hostname of the current environment. Defaults to `window.location.hostname`                                           |
+
+The recognized environments are:
+
+| Environment       | Description                                                                  |
+| :---------------- | :--------------------------------------------------------------------------- |
+| **dev**           | Development environment (i.e., `localhost`, `127.0.0.1`)                     |
+| **go**            | Production environment                                                       |
+| **qa**            | QA environment                                                               |
+| **next**          | Next environment                                                             |
+| **stage**         | Staging environment                                                          |
+| **test**          | Unit test environment (i.e., `process.env.NODE_ENV === 'test'`)              |
+| `<string>`        | Custom environment that matches against hostname `<string>.servicetitan.com` |
+| `<string>.st.dev` | Custom environment that matches against hostname `<string>.st.dev`           |
+
+### Custom environments
+
+Custom environments are for applications and services that run separately from the Monolith.
+For example, to associate **prod** with `my-service.servicetitan.com` and **stage** with `my-service-stage.st.dev`:
+
+```json
+{
+    "my-service": "prod", // Matches my-service.servicetitan.com
+    "stage.st.dev": "stage" // Matches *stage.st.dev
+}
+```
+
+### Examples
+
+Determine LaunchDarkly client-side ID for TitanAdvisor project.
+
+```tsx
+function useTitanAdvisorClientSideID() {
+    // Environment won't change and is safe to memoize
+    return useMemo(() => {
+        return getValueForEnvironment({
+            dev: '669fe6e5cc97eb103be7a620',
+            go: '669fe5bff00a0c0fa60b25e4',
+            next: '669fe5bff00a0c0fa60b25e4', // same a 'go' but could also be 'qa'
+            qa: '669fe6d6f00a0c0fa60b2721',
+            stage: '669fe65979abf310b860236e',
+        });
+    }, []);
+}
+```
+
+:::info
+Note that because the environment is fixed for the life the application, it is safe to memoize the return value.
+:::
+
+:::caution
+Do not call `getValueForEnvironment` globally, outside a React component or hook. That usage assumes that all the information needed to determine the environment is available immediately when the Javascript runtime loads and before the application is initialized. While that might work, it might also change in the future.
+:::

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@servicetitan/docs-uikit",
-    "version": "30.0.0",
+    "version": "30.1.1",
     "description": "",
     "repository": {
         "type": "git",
@@ -16,5 +16,5 @@
     "cli": {
         "webpack": false
     },
-    "gitHead": "e182cbb85cf66d62f235a9ca172fc04dc705fd0a"
+    "gitHead": "02382f349ee120e1b30d9676484481f93059c054"
 }