@servicetitan/docs-uikit 31.0.0 → 31.1.0

package/docs/launchdarkly-service.mdx

@@ -140,6 +140,30 @@ export const HostApp: FC = () => {
 };
 ```
 
+### LDService
+
+The `LDService` interface enables [headless bundles](./web-components/headless-loader#headlesscallback) to create and reuse client connections for LaunchDarkly projects.
+
+```ts
+export interface LDService {
+    getClient: (config: ClientConfig) => LDClient;
+}
+
+export interface ClientConfig {
+    clientSideID: string;
+    context?: LDContext;
+}
+```
+
+#### getClient
+
+Returns an `LDClient` instance configured with the following parameters.
+
+| Name           | Type     | Description                                                         |
+| :------------- | :------- | :------------------------------------------------------------------ |
+| `clientSideID` | `string` | The LaunchDarkly client-side ID.                                    |
+| `context`      | `object` | (Optional) Context for targeting rules. Defaults to anonymous user. |
+
 ### FeatureFlagStore
 
 `LDProvider` automatically provides a `FeatureFlagStore` that allows you to access

package/docs/startup/start.mdx

@@ -15,4 +15,4 @@ Runs package in the development mode. Applications will be hosted on sequential
 
 The `start` command executes the same steps as the `build` command, then watches for changes and automatically reruns each step as needed.
 
-See [Build Steps](/docs/startup/build#build-steps).
+See [Build Steps](/docs/frontend/uikit/startup/build#build-steps).

package/docs/startup/startup.mdx

@@ -189,7 +189,7 @@ Use package-specific `tsconfig.json` and `tsconfig.build.json` files to set or o
 }
 ```
 
-`tsconfig.build.json` takes precedence over `tsconfig.json`. Use `tsconfig.build.json` that extends from `tsconfig.json` to exclude tests and mocks from type checking during development. E.g.,
+`tsconfig.build.json` takes precedence over `tsconfig.json`. Use `tsconfig.build.json` that extends from `tsconfig.json` to exclude tests, stories, and mocks from type checking during development. E.g.,
 
 :::caution
 If your `tsconfig.json` configures project references they must be duplicated in `tsconfig.build.json`.
@@ -200,7 +200,7 @@ See [references are not inherited in tsconfig.json](https://github.com/microsoft
 ```json title="tsconfig.build.json"
 {
     "extends": "./tsconfig.json",
-    "exclude": ["**/__tests__/*", "**/*.test.*", "**/__mocks__/*"],
+    "exclude": ["**/__tests__/*", "**/*.test.*", "**/__mocks__/*", "**/*.stories.*"],
     "references": [
         { "path": "../feature-a" },
         { "path": "../feature-b" },
@@ -284,6 +284,10 @@ Or you can use relative path to a file that exports an object with detailed conf
 
 See [MFE configuration](/docs/frontend/micro-frontends/#mfe-configuration) for detailed instructions on configuring MFE applications.
 
+###### Headless bundle
+
+If a file named `headless.ts` is present in the source folder of an MFE package, `startup` automatically generates a headless bundle alongside the `light` and `full` bundles. See [web-components documentation](../web-components/headless-loader) for information on the headless bundle.
+
 #### Webpack
 
 Use `cli.webpack` to set or override Webpack options.

package/docs/web-components/headless-loader.mdx

@@ -0,0 +1,67 @@
+---
+title: HeadlessLoader
+---
+
+The headless bundle is a tiny bundle that allows a host to preload configuration or setup information without having to load the entire MFE. The headless bundle does not utilize React, and cannot use any modules that require React.
+
+## Generating headless bundle
+
+To generate a headless bundle, create a file named `headless.ts` in the root directory of the MFE's source folder. When this file is present, startup generates a `headless` bundle alongside the `light` and `full` bundles. Only what is imported in `headless.ts` will be included in the bundle.
+
+`headless.ts` should contain exported functions named `connectedCallback` and/or `disconnectedCallback`.
+
+### `connectedCallback`
+
+`connectedCallback` will be called when the bundle is loaded in the host. It should be typed as `HeadlessCallback<T>`.
+
+```ts title="src/headless.ts"
+import type { HeadlessCallback } from '@servicetitan/web-components';
+export const connectedCallback: HeadlessCallback<ExampleData> = ({ mfeData, eventBus }) => {
+    doSomethingWithMfeData(mfeData);
+    eventBus?.emit('example-module:status', { status: 'connected', timestamp: Date.now() });
+};
+```
+
+
+### `disconnectedCallback`
+
+`disconnectedCallback` will be called when the headless MFE is unmounted. It should be typed as `HeadlessCallback<T>`.
+
+```ts title="src/headless.ts"
+import type { HeadlessCallback } from '@servicetitan/web-components';
+export const disconnectedCallback: HeadlessCallback = ({ eventBus }) => {
+    eventBus?.emit('example-module:status', { status: 'disconnected', timestamp: Date.now() });
+};
+```
+
+### `HeadlessCallback<T>`
+
+The `HeadlessCallback<T>` type is a function that receives an object with the below properties:
+
+| Parameter    | Type              | Description                                                                                    |
+| ------------ | ----------------- | ---------------------------------------------------------------------------------------------- |
+| `ldService`  | `LDService`       | The [LaunchDarkly LDService instance](../launchdarkly-service#ldservice) passed from the Host. |
+| `logService` | `Log`             | The [Log instance](../log-service#log) passed from the Host.                                       |
+| `eventBus`   | `EventBus`        | The [EventBus instance](./event-bus) passed from the Host.                                     |
+| `mfeData`    | `Serializable<T>` | The [data passed from the host into `HeadlessLoader`](#headless-loader-props), typed as `T`.   |
+
+## HeadlessLoader
+
+Use the `HeadlessLoader` component to load this bundle from within a host application.
+
+```tsx
+import { HeadlessLoader } from '@servicetitan/web-components';
+
+export const Foo = () => {
+    return <HeadlessLoader src="https://unpkg.servicetitan.com/{package_name}@{semver_range}" />;
+};
+```
+
+### Props  {#headless-loader-props}
+
+| Name          | Description                                                                                                                                         |
+| :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src`         | url for the MFE's package                                                                                                                           |
+| `fallbackSrc` | optional alternative url for the MFE's package (if request for src returns error)                                                                   |
+| `data`        | additional data passed to an MFE as an object, where values are serializable, and preferably memoized ([see Loader](./loader#passing-data-from-host-to-mfe)) |
+| `cache`       | optional cache strategy for the MFE [(see Loader)](./loader#cache-strategy). Defaults to `-1`.                                                               |

package/docs/web-components/loader.mdx

@@ -0,0 +1,235 @@
+---
+title: Loader
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+## 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 = () => {
+    return <Loader src="https://unpkg.servicetitan.com/{package_name}@{semver_range}" />;
+};
+```
+
+### Props
+
+| Name                     | Description                                                                                                                                         |
+| :----------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src`                    | url for the MFE's package                                                                                                                           |
+| `fallbackSrc`            | optional alternative url for the MFE's package (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). Defaults to `-1`.                                                              |
+
+### 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).
+- `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). This is the default value.
+- _&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.
+
+### Using EventBus to exchanges messages
+
+Use [EventBus](./event-bus) to exchange messages between the host and MFEs.
+When an EventBus is provided via `EVENT_BUS_TOKEN`, `Loader` automatically passes it through to MFEs.
+For example,
+
+<Tabs
+    defaultValue="host"
+    values={[
+        { label: 'Host', value: 'host' },
+        { label: 'MFE', value: 'mfe'},
+        { label: 'Types', value: 'types' },
+    ]}
+>
+<TabItem value="types">
+
+```tsx
+import { EventBus, typedEventBusToken } from '@servicetitan/web-components';
+
+export enum Events {
+    example = 'example:event',
+}
+
+export interface ExampleEvents {
+    [Events.example]: undefined;
+}
+
+export type ExampleEventBus = EventBus<ExampleEvents>;
+
+export const EXAMPLE_EVENT_BUS_TOKEN = typedEventBusToken<ExampleEvents>();
+```
+
+</TabItem>
+<TabItem  value="host">
+
+```tsx
+import { provide, useDependencies } from '@servicetitan/react-ioc';
+import { EVENT_BUS_TOKEN, EventBus, Loader } from '@servicetitan/web-components';
+import { FC, useCallback, useEffect } from 'react';
+import { Events, EXAMPLE_EVENT_BUS_TOKEN } from './types';
+
+const mfeUrl = 'https://unpkg.servicetitan.com/@servicetitan/examples';
+
+export const App: FC = provide({
+    singletons: [{ provide: EVENT_BUS_TOKEN, useValue: new EventBus() }],
+})(() => {
+    const [eventBus] = useDependencies(EXAMPLE_EVENT_BUS_TOKEN);
+    const handleExampleEvent = useCallback(() => {
+        /* Handle event */
+    }, []);
+
+    useEffect(() => {
+        eventBus.on(Events.example, handleExampleEvent);
+        return () => {
+            eventBus.off(Events.example, handleExampleEvent);
+        };
+    }, [eventBus, handleExampleEvent]);
+
+    // Loader passes provided EventBus through to MFE
+    return <Loader src={mfeUrl} />;
+});
+```
+
+</TabItem>
+<TabItem value="mfe">
+
+```tsx
+import { Button } from '@servicetitan/anvil2';
+import { useDependencies } from '@servicetitan/react-ioc';
+import { useCallback } from 'react';
+import { Events, EXAMPLE_EVENT_BUS_TOKEN } from './types';
+
+export const App = () => {
+    // Loader passes through provided EventBus
+    const [eventBus] = useDependencies(EXAMPLE_EVENT_BUS_TOKEN);
+
+    const handleClick = useCallback(() => {
+        eventBus.emit(Events.example);
+    }, [eventBus]);
+
+    return <Button onClick={handleClick}>Click me</Button>;
+};
+```
+
+</TabItem>
+</Tabs>
+
+See [typedEventBusToken](./event-bus#typedeventbustoken) for a detailed explanation
+of the types used in these examples.
+
+#### Using legacy ref parameter
+
+For backward compatibility, when no `EVENT_BUS_TOKEN` is provided, `Loader`
+creates a private EventBus and returns it via the `ref` parameter.
+This old approach should not be used in new code.
+
+```tsx
+import { FC, useCallback, useEffect, useState } from 'react';
+import { Loader } from '@servicetitan/web-components';
+import { Events, ExampleEventBus } from './types';
+
+const mfeUrl = 'https://unpkg.servicetitan.com/@servicetitan/examples';
+
+export const Component: FC = () => {
+    const [eventBus, setEventBus] = useState<ExampleEventBus | null>(null);
+    const handleExampleEvent = useCallback(() => {
+        /* Handle event */
+    }, []);
+
+    useEffect(() => {
+        eventBus?.on(Events.example, handleExampleEvent);
+        return () => {
+            eventBus?.off(Events.example, handleExampleEvent);
+        };
+    }, [eventBus, handleExampleEvent]);
+
+    // Loader provides private EventBus and returns it via "ref"
+    return <Loader ref={ref => setEventBus(ref)} src={mfeUrl} />;
+};
+```
+
+:::caution
+Note, if an `EVENT_BUS_TOKEN` is provided, `Loader` returns the provide value in `ref`
+and doesn't create a private EventBus.
+:::

package/docs/web-components/use-mfe-data-context.mdx

@@ -0,0 +1,17 @@
+---
+title: useMFEDataContext
+---
+
+If data is provided to an MFE via `<Loader>`, the  data can 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>();
+};
+```

package/docs/web-components/use-mfe-metadata-context.mdx

@@ -0,0 +1,20 @@
+---
+title: useMFEMetadataContext
+---
+
+Metadata, such as `shadowRoot` and `portalShadowRoot`, is provided to MFEs. It 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 |

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

@@ -2,273 +2,15 @@
 title: Web Components
 ---
 
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
 #### [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 = () => {
-    return <Loader src="https://unpkg.servicetitan.com/{package_name}@{semver_range}" />;
-};
-```
-
-### Props
-
-| Name                     | Description                                                                                                                                         |
-| :----------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `src`                    | url for the MFE's package                                                                                                                           |
-| `fallbackSrc`            | optional alternative url for the MFE's package (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.
-
-### Using EventBus to exchanges messages
-
-Use [EventBus](./event-bus) to exchange messages between the host and MFEs.
-When an EventBus is provided via `EVENT_BUS_TOKEN`, `Loader` automatically passes it through to MFEs.
-For example,
-
-<Tabs
-    defaultValue="host"
-    values={[
-        { label: 'Host', value: 'host' },
-        { label: 'MFE', value: 'mfe'},
-        { label: 'Types', value: 'types' },
-    ]}
->
-<TabItem value="types">
-
-```tsx
-import { EventBus, typedEventBusToken } from '@servicetitan/web-components';
-
-export enum Events {
-    example = 'example:event',
-}
-
-export interface ExampleEvents {
-    [Events.example]: undefined;
-}
-
-export type ExampleEventBus = EventBus<ExampleEvents>;
-
-export const EXAMPLE_EVENT_BUS_TOKEN = typedEventBusToken<ExampleEvents>();
-```
-
-</TabItem>
-<TabItem  value="host">
-
-```tsx
-import { provide, useDependencies } from '@servicetitan/react-ioc';
-import { EVENT_BUS_TOKEN, EventBus, Loader } from '@servicetitan/web-components';
-import { FC, useCallback, useEffect } from 'react';
-import { Events, EXAMPLE_EVENT_BUS_TOKEN } from './types';
-
-const mfeUrl = 'https://unpkg.servicetitan.com/@servicetitan/examples';
-
-export const App: FC = provide({
-    singletons: [{ provide: EVENT_BUS_TOKEN, useValue: new EventBus() }],
-})(() => {
-    const [eventBus] = useDependencies(EXAMPLE_EVENT_BUS_TOKEN);
-    const handleExampleEvent = useCallback(() => {
-        /* Handle event */
-    }, []);
-
-    useEffect(() => {
-        eventBus.on(Events.example, handleExampleEvent);
-        return () => {
-            eventBus.off(Events.example, handleExampleEvent);
-        };
-    }, [eventBus, handleExampleEvent]);
-
-    // Loader passes provided EventBus through to MFE
-    return <Loader src={mfeUrl} />;
-});
-```
-
-</TabItem>
-<TabItem value="mfe">
-
-```tsx
-import { Button } from '@servicetitan/anvil2';
-import { useDependencies } from '@servicetitan/react-ioc';
-import { useCallback } from 'react';
-import { Events, EXAMPLE_EVENT_BUS_TOKEN } from './types';
-
-export const App = () => {
-    // Loader passes through provided EventBus
-    const [eventBus] = useDependencies(EXAMPLE_EVENT_BUS_TOKEN);
-
-    const handleClick = useCallback(() => {
-        eventBus.emit(Events.example);
-    }, [eventBus]);
-
-    return <Button onClick={handleClick}>Click me</Button>;
-};
-```
-
-</TabItem>
-</Tabs>
-
-See [typedEventBusToken](./event-bus#typedeventbustoken) for a detailed explanation
-of the types used in these examples.
-
-#### Using legacy ref parameter
-
-For backward compatibility, when no `EVENT_BUS_TOKEN` is provided, `Loader`
-creates a private EventBus and returns it via the `ref` parameter.
-This old approach should not be used in new code.
-
-```tsx
-import { FC, useCallback, useEffect, useState } from 'react';
-import { Loader } from '@servicetitan/web-components';
-import { Events, ExampleEventBus } from './types';
-
-const mfeUrl = 'https://unpkg.servicetitan.com/@servicetitan/examples';
-
-export const Component: FC = () => {
-    const [eventBus, setEventBus] = useState<ExampleEventBus | null>(null);
-    const handleExampleEvent = useCallback(() => {
-        /* Handle event */
-    }, []);
-
-    useEffect(() => {
-        eventBus?.on(Events.example, handleExampleEvent);
-        return () => {
-            eventBus?.off(Events.example, handleExampleEvent);
-        };
-    }, [eventBus, handleExampleEvent]);
-
-    // Loader provides private EventBus and returns it via "ref"
-    return <Loader ref={ref => setEventBus(ref)} src={mfeUrl} />;
-};
-```
-
-:::caution
-Note, if an `EVENT_BUS_TOKEN` is provided, `Loader` returns the provide value in `ref`
-and doesn't create a private EventBus.
-:::
-
-## 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.
+## API
 
-| 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 |
+- [Loader](./loader.mdx) - Use `Loader` to load an MFE into a host application.
+- [HeadlessLoader](./headless-loader.mdx) - Use `HeadlessLoader` to load the headless bundle to perform logic, such as messaging, with no UI, and without requiring the full or light bundle to be loaded.
+- [EventBus](./event-bus.mdx) - Use `EventBus` to exchange messages (aka events) between a host and MFEs, or between concurrently mounted MFEs.
+- [useMFEDataContext](./use-mfe-data-context.mdx) - Use `useMFEDataContext` hook to access data provided to the MFE.
+- [useMFEMetadataContext](./use-mfe-metadata-context.mdx) - Use `useMFEMetadataContext` hook to access metadata about the MFE.
+- [getValueForEnvironment](./get-value-for-environment.mdx) - Use `getValueForEnvironment` to detect the host environment and return a corresponding value.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@servicetitan/docs-uikit",
-    "version": "31.0.0",
+    "version": "31.1.0",
     "description": "",
     "repository": {
         "type": "git",
@@ -16,5 +16,5 @@
     "cli": {
         "webpack": false
     },
-    "gitHead": "c52e188a1217df74052774a2eea6a5126089e3d5"
+    "gitHead": "d01cfe32c50461245ce52c911710e8eb879290e9"
 }