@servicetitan/docs-uikit 30.3.1 → 31.1.0

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": "30.3.1",
+    "version": "31.1.0",
     "description": "",
     "repository": {
         "type": "git",
@@ -16,5 +16,5 @@
     "cli": {
         "webpack": false
     },
-    "gitHead": "4d7f01d86d64fc00160d63a2e2a3448f28aa7a2d"
+    "gitHead": "d01cfe32c50461245ce52c911710e8eb879290e9"
 }