@servicetitan/docs-uikit 32.1.0 → 32.2.0

package/docs/BREAKING_CHANGES.mdx

@@ -1,5 +1,6 @@
 ---
 title: BREAKING CHANGES
+sidebar_position: 0
 ---
 
 ## v32.0.0

package/docs/launchdarkly-service.mdx

@@ -142,7 +142,7 @@ 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.
+The `LDService` interface enables [headless bundles](./microfrontends/developing/headless-bundle) to create and reuse client connections for LaunchDarkly projects.
 
 ```ts
 export interface LDService {

package/docs/microfrontends/developing/authentication.mdx

@@ -0,0 +1,91 @@
+---
+title: Authentication
+---
+
+To develop against backend APIs that require authentication, you can configure [proxies](https://webpack.js.org/configuration/dev-server/#devserverproxy) that add cookies to local requests.
+
+## Create proxy script
+
+Create a script that generates a `webpack-dev-server` proxy configuration from a local `config.js` file that maps URLs to cookies. For example,
+
+```js title="local/proxy-settings.js"
+const proxy = [];
+
+try {
+    /**
+     * Here map environments to the endpoints (prefixes) that require authentication
+     * (if all do, use the ** wildcard). If all requests are sent to the host,
+     * remove or comment out the "ms" (microservice) environment.
+     */
+    const environments = {
+        mainApp: ['/app/api'],
+        ms: ['**'],
+    };
+
+    // Read local config
+    const config = require('./config');
+
+    // Add proxy for each URL and cookie in local config
+    Object.entries(environments).forEach(([name, prefixes]) => {
+        const { cookie, url } = config[name] || {};
+        if (url && cookie) {
+            proxy.push(createProxyConfig({ target: url, cookie, context: prefixes }));
+        }
+    });
+} catch {
+    // ignore error
+}
+
+function createProxyConfig({ context, cookie, target }) {
+    return {
+        context,
+        target,
+        changeOrigin: true,
+        secure: false,
+        onProxyReq: req => {
+            if (cookie) {
+                req.setHeader('Cookie', cookie);
+            }
+        },
+    };
+}
+
+module.exports = proxy.length ? proxy : undefined;
+```
+
+## Put cookies in local configuration file
+
+Login to the application and use the web browser's Developer Tools to copy the cookies from backend requests to `config.js`.
+
+```js title="local/config.js"
+module.exports = {
+    mainApp: {
+        url: 'https://go.servicetitan.com/',
+        cookie: '', // actual cookie goes here
+    },
+    ms: {
+        url: 'http://localhost:8888',
+        cookie: '', // actual cookie goes here
+    },
+};
+```
+
+:::caution
+Add `config.js` to `.gitignore` so the cookies are not exposed. And, note that
+you will have to replace cookies when they expire.
+:::
+
+## Configure `webpack-dev-server`
+
+Set `cli.webpack.proxy` to the relative path to the proxy script.
+
+```json title="packages/mfe/package.json"
+{
+    "cli": {
+        "webpack": {
+            "port": 8888,
+            "proxy": "../../local/proxy-settings.js"
+        }
+    }
+}
+```

package/docs/microfrontends/developing/developing.mdx

@@ -0,0 +1,124 @@
+---
+title: Developing
+---
+
+An MFE is a React component that is bundled in such a way that it renders inside an isolated host container.
+
+A best practice is to use different MFEs for different purposes. Creating multi-tasking MFEs that serve multiple, unrelated purposes is usually a suboptimal approach.
+Components that conditionally render different behaviors based on inputs from the host should probably be implemented as separate MFEs.
+
+To create an MFE, create a file named `app.tsx` in the root directory of a package's source folder (the `rootDir` in `tsconfig.json`) that exports a component named `App`. The `App` component will be the MFE's entry point.
+
+Remove any existing "index" file from the root directory and, if the MFE uses `@servicetitan/design-system`, remove all imports of design system styles from the code (`startup` automatically imports design system styles when needed).
+
+:::tip
+
+- If the MFE is large, use [`lazyModule`](../../lazy-module) to split it into smaller modules that are loaded on demand.
+- See [Headless Bundle](./headless-bundle) for how to create a separate bundle for preloading setup or configuration information.
+
+:::
+
+## Configuration
+
+In the MFE's `package.json`, set,
+
+- `private` to `true`
+- `cli.web-component` to `true`,
+- `cli.webpack.port` to a free port from where to serve the MFE locally
+- `publishConfig.access` to `"private"`
+
+E.g.,
+
+```json title="package.json"
+{
+    "private": true,
+    "cli": {
+        "web-component": true,
+        "webpack": {
+            "port": 8888
+        }
+    },
+    "publishConfig": {
+        "access": "restricted"
+    }
+}
+```
+
+### Required dependencies
+
+Add these required **dependencies** (include other dependencies as needed):
+
+- `@servicetitan/log-service`
+- `@servicetitan/react-ioc`
+- `@servicetitan/web-components`
+- `history`
+- `react`
+- `react-dom`
+
+## Running
+
+Use [startup start](../../startup/start) to run the MFE. It will serve it from the port specified [above](#configuration).
+
+:::tip
+See [Authentication](./authentication) for how to develop against backend APIs that require authentication.
+:::
+
+### Inside host application
+
+To run the MFE in a local host, pass [Loader](../../web-components/loader) the MFE's local URL. For example,
+
+```tsx title="Local Host Application"
+import { Loader } from '@servicetitan/web-components';
+
+export function MyMfe() {
+    return <Loader src="http://localhost:8888" />;
+}
+```
+
+#### Using `getValueForEnvironment` in the Monolith
+
+In the Monolith, you can use [getValueForEnvironment](../../web-components/get-value-for-environment) to automatically use the MFE's local URL in development. E.g.,
+
+```tsx title="Monolith Host Application"
+import { Loader, getValueForEnvironment } from '@servicetitan/web-components';
+
+const baseUrl = 'https://unpkg.servicetitan.com/@servicetitan/my-mfe';
+
+export function MyMfe() {
+    return <Loader src={getMfeUrl()} />;
+}
+
+function getMfeUrl() {
+    return (
+        getValueForEnvironment({
+            dev: 'http://localhost:8888',
+            qa: `${baseUrl}@qa`,
+            stage: `${baseUrl}@stage`,
+            go: `${baseUrl}@prod`,
+            next: `${baseUrl}@prod`,
+        }) ?? ''
+    );
+}
+```
+
+### Without start
+
+To run the MFE without `start`, [build](#building) it, then point any static http server to the MFE's root folder, where [Loader](../../web-components/loader) will find the `dist` directory. For example, to serve with [`http-server`](https://www.npmjs.com/package/http-server) on port 8888,
+
+```sh
+npx --yes http-server packages/mfe -p 8888 --cors
+```
+
+## Building
+
+Use [startup build](../../startup/build) to build the MFE.
+
+## See Also
+
+- [Authentication](./authentication) - how to use backend API's that require authentication
+- [Example MFE](https://github.com/servicetitan/frontend-example/tree/master/packages/mfe)
+- [Headless Bundle](./headless-bundle) - how to preloading setup or configuration information
+- [Hosting](../hosting) - how to load MFEs
+- [Publishing](../publishing) - how to publish MFEs
+- [Sharing Dependencies](../sharing-dependencies) - how to customize shared dependencies
+- [Web Components](../../web-components) - how to use `Loader`, `getValueForEnvironment` and other runtime APIs

package/docs/microfrontends/developing/headless-bundle.mdx

@@ -0,0 +1,62 @@
+---
+title: Headless Bundle
+---
+
+A headless bundle is a tiny bundle that allows hosts to preload configuration or setup information without having to load the entire MFE. Headless bundles are not rendered into or associated with DOM elements so they cannot use React.
+
+To generate a headless bundle, create a file named `headless.ts` in the root directory of the MFE's source folder (the `rootDir` in `tsconfig.json`) and export a function named `connectedCallback`.
+
+:::info
+`Startup` includes everything imported by `headless.ts` in the bundle.
+Headless bundles are wholly self-contained and cannot [share dependencies](../sharing-dependencies) with hosts.
+:::
+
+## connectedCallback
+
+The host calls `connectedCallback` when the bundle is loaded.
+
+```ts title="src/headless.ts"
+import type { HeadlessCallback } from '@servicetitan/web-components';
+
+export const connectedCallback: HeadlessCallback<ExampleData> = ({ mfeData, eventBus }) => {
+    // Process host data
+    doSomethingWithMfeData(mfeData);
+
+    // Send message to host
+    eventBus?.emit('example-module:status', { status: 'connected', timestamp: Date.now() });
+};
+```
+
+See [HeadlessCallback](#headlesscallback) for a detailed description of `connectedCallback`s parameters.
+
+## disconnectedCallback
+
+If `headless.ts` exports a function named `disconnectedCallback`, the host calls it when the bundle is unmounted.
+
+```ts title="src/headless.ts"
+import type { HeadlessCallback } from '@servicetitan/web-components';
+
+export const disconnectedCallback: HeadlessCallback = ({ eventBus }) => {
+    // Send message to host
+    eventBus?.emit('example-module:status', { status: 'disconnected', timestamp: Date.now() });
+};
+```
+
+See [HeadlessCallback](#headlesscallback) for a detailed description of `disconnectedCallback`s parameters.
+
+## HeadlessCallback
+
+`HeadlessCallback<TMfeData = any, TEventBus extends EventBus = EventBus>`
+
+The `connectedCallback` and `disconnectedCallback` functions are passed a single argument that is an object with the following fields:
+
+| Name         | 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`   | `TEventBus`              | The [EventBus instance](../../web-components/event-bus) passed from the Host, typed as `TEventBus`.                                   |
+| `mfeData`    | `Serializable<TMfeData>` | The [data passed from the host to `HeadlessLoader`](../../web-components/headless-loader#headless-loader-props), typed as `TMfeData`. |
+
+## Loading
+
+Use [HeadlessLoader](../../web-components/headless-loader) to load headless bundles.

package/docs/microfrontends/hosting.mdx

@@ -0,0 +1,84 @@
+---
+title: Hosting
+---
+
+A host is an application, or MFE, that uses [`Loader`](../web-components/loader) to dynamically fetch and render MFEs.
+
+## Configuration
+
+Set `cli.webpack.expose-shared-dependencies` to `true` in the application's `package.json`.
+
+:::caution
+`expose-shared-dependencies` only applies to applications. MFEs that load other MFEs do not need this setting or any additional configuration.
+:::
+
+```json title="package.json"
+{
+    "cli": {
+        "webpack": {
+            "expose-shared-dependencies": true
+        }
+    }
+}
+```
+
+### Design system
+
+If the host uses `@servicetitan/design-system` remove all imports of design system styles form the code; `startup` handles that automatically. Alternatively, to customize the design system styles, move the imports to a file named `design-system.css` in the root directory of the application's source folder (the `rootDir` in `tsconfig.json`). E.g.,
+
+```css title="design-system.css"
+@import '@servicetitan/tokens/dist/tokens.css';
+@import '@servicetitan/anvil-fonts/dist/css/anvil-fonts.css';
+@import '@servicetitan/design-system/dist/system.min.css';
+```
+
+## Loading MFEs
+
+ServiceTitan serves MFEs from a private UNPKG instance at https://unpkg.servicetitan.com.
+To load an MFE, pass [`Loader`](../web-components/loader) its UNPKG url. For example,
+
+```tsx
+import { Loader } from '@servicetitan/web-components';
+
+const mfeUrl = 'https://unpkg.servicetitan.com/@servicetitan/example-mfe';
+
+export function ExampleMfe() {
+    return <Loader src={mfeUrl} />;
+}
+```
+
+### Using tags
+
+In practice hosts usually append a tag of the form `@{version}`to the URL to specify which version to load. Tags can be an exact version (e.g., **@0.0.0-next.152efeb**) or an release tag like **@prod**.
+
+In the Monolith, you can use [getValueForEnvironment](../web-components/get-value-for-environment) to determine the release tag from the host's environment,
+
+```tsx
+import { Loader, getValueForEnvironment } from '@servicetitan/web-components';
+
+const baseUrl = 'https://unpkg.servicetitan.com/@servicetitan/example-mfe';
+
+export function ExampleMfe() {
+    return <Loader src={getMfeUrl()} />;
+}
+
+function getMfeUrl() {
+    return (
+        getValueForEnvironment({
+            dev: 'http://localhost:8888',
+            qa: `${baseUrl}@qa`,
+            stage: `${baseUrl}@stage`,
+            go: `${baseUrl}@prod`,
+            next: `${baseUrl}@prod`,
+        }) ?? ''
+    );
+}
+```
+
+## See Also
+
+- [Developing](./developing) - how to create MFEs
+- [Example host application](https://github.com/servicetitan/frontend-example/tree/master/packages/application)
+- [Publishing](./publishing) - how to publish MFEs
+- [Sharing Dependencies](./sharing-dependencies) - how to customize shared dependencies
+- [Web Components](../web-components) - how to use `Loader`, `getValueForEnvironment` and other runtime APIs.

package/docs/microfrontends/microfrontends.mdx

@@ -0,0 +1,45 @@
+---
+title: Microfrontends (MFEs)
+sidebar_position: 1
+---
+
+Microfrontends (MFEs) break a large frontend application into independently developed, deployed, and versioned pieces so teams can move faster and reduce cross-team coupling.
+
+:::info
+ServiceTitan's MFE solution predates Webpack's module federation.
+For a discussion of the pros and cons and why we continue to use ServiceTitan's solution see this [document](https://github.com/servicetitan/dispatch-docs/blob/5fd062ec6a7f292be593484a633c892ca34c8de7/architecture-decisions/0007-mfe-monolith-shared-code-and-dependencies.md).
+:::
+
+## Benefits
+
+- Enable independent release cadence and ownership
+- Let teams choose and upgrade dependencies independently
+- Improve fault isolation and reliability at scale
+- Allow reuse of UI pieces that are standalone
+- Maintain performance by reusing compatible dependencies
+
+## Restrictions
+
+- Stores or services from the host application cannot be shared with MFEs
+- Passing data via `window` or global variables is discouraged
+- Use [Loader's data prop](../web-components/loader#passing-data-from-host-to-mfe) or [`EventBus`](../web-components/event-bus) to exchange data between hosts and MFEs
+    - Data must be serializable
+    - Changes must be backward compatible, because hosts and MFEs release independently
+
+## Design
+
+[`Startup`](../startup/) builds MFEs. It outputs two bundles, and metadata about the MFE's capabilities and dependencies. The **full** bundle is self-contained and includes all code required by the MFE. The **light** bundle contains only private dependencies that aren't shared with hosts.
+
+Teams publish MFE's to ServiceTitan private [Verdaccio + UNPKG](/docs/frontend/verdaccio-unpkg) infrastructure.
+
+At runtime, [`Loader`](../web-components/loader) fetches the MFE's metadata, selects either the **light** or **full** bundle depending on whether the host's dependencies are compatible, then renders the MFE inside a Shadow DOM that minimizes conflicts.
+
+## Topics
+
+See the following topics for how to build, deploy and use MFEs:
+
+- [Developing](./developing/) - how to create MFEs
+- [Hosting](./hosting) - how to load MFEs
+- [Publishing](./publishing) - how to publish MFEs
+- [Sharing Dependencies](./sharing-dependencies) - how to customize shared dependencies
+- [Troubleshooting](./troubleshooting) - how to fix common issues

package/docs/microfrontends/publishing.mdx

@@ -0,0 +1,93 @@
+---
+title: Publishing
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+MFEs must be published before they can be loaded in production.
+
+:::note
+This document describes using UNPKG + Verdaccio, the recommended way to publish MFEs. There are alternative ways of serving MFEs (e.g., from a microservice) that are not recommended and are not described in this document.
+:::
+
+## Publishing Locally
+
+Before you can publish locally, run the following command to add an authorization token for Verdaccio to the local NPM configuration:
+
+```sh
+npx verdaccio-okta-oauth@latest --registry https://verdaccio.servicetitan.com
+```
+
+[Build](../startup/build) the MFE, then to publish it run:
+
+```sh
+npx startup mfe-publish
+```
+
+:::info
+If the project contains multiple MFEs `startup` publishes all of them.
+:::
+
+## Publishing From CI
+
+To publish an MFE from a Github or Teamcity workflow, use the `ST_VERDACCIO_PUBLISH_TOKEN` organization secret to authorize access to Verdaccio. For example,
+
+<Tabs
+defaultValue="github"
+values={[{ label: "Github Action", value: "github"}, {label: "Dockerfile", value: "docker"}]}>
+
+<TabItem value="github">
+
+```yml
+- name: Build project
+  run: npm run build
+
+- name: Configure Verdaccio token
+  run: npm config set --location=project "//verdaccio.servicetitan.com/:_authToken"="${{ secrets.ST_VERDACCIO_PUBLISH_TOKEN }}"
+
+- name: Publish MFE
+  run: npm run mfe-publish
+```
+
+</TabItem>
+<TabItem value="docker">
+
+```dockerfile
+ARG ST_VERDACCIO_PUBLISH_TOKEN
+
+RUN npm run build
+RUN npm config set --location=project "//verdaccio.servicetitan.com/:_authToken=$ST_VERDACCIO_PUBLISH_TOKEN"
+RUN npm run mfe-publish
+```
+
+</TabItem>
+</Tabs>
+
+## Managing Releases With Tags
+
+Release tags like **dev**, **next**, and **prod** are a lightweight way to control which MFE bundle consumers load, without changing host code. You can use tags to promote, test, or roll back releases independently from the host application.
+
+### Key concepts
+
+- A release tag points to a specific published package version.
+- Hosts pass a tag instead of an exact version to [Loader](../web-components/loader).
+- Switching the tag to a different version changes what hosts load.
+
+:::caution
+When a tag is switched to a new version, it could take ServiceTitan's infrastructure up to fifteen minutes to deliver the new version to consumers.
+:::
+
+### Common workflows
+
+- **Canary testing**: publish MFE as `0.0.0-develop.{hash}` and tag as **dev** for early testing.
+- **Staging promotion**: point **next** to the version used to use in pre-production environments.
+- **Production promotion**: point **prod** to the release that passed staging.
+- **Rollback**: repoint a tag to the previous good version to revert consumers.
+
+## See Also
+
+- [Example `mfe-publish` workflow](https://github.com/servicetitan/frontend-example/blob/master/.github/workflows/mfe-publish.yml)
+- [startup mfe-publish](../startup/mfe-publish) -- how to tag releases
+- [Using tags](./hosting#using-tags) -- how to load MFEs with tags
+- [Verdaccio + UNPKG](/docs/frontend/verdaccio-unpkg) -- publishing infrastructure

package/docs/microfrontends/sharing-dependencies.mdx

@@ -0,0 +1,96 @@
+---
+title: Sharing Dependencies
+---
+
+When `startup` builds an MFE, it creates two bundles, named **full** and **light**:[^headless]
+
+- The **full** bundle is completely self-contained and includes all code required by the MFE.
+- The **light** bundle is smaller and faster because it omits dependencies that already exist in the host (e.g., `react`, `@servicetitan/design-system`).
+
+At runtime, the host loads the **light** bundle when its shared dependencies are compatible with the MFE's, else it loads the **full** bundle.
+
+To be compatible, the host's version of a dependency must satisfy the MFE's [semver](https://semver.org) range. To allow the widest compatibility MFEs should use `^` instead of `~` for shared dependencies. For example, a host using `react` `18.3.1` will consider itself compatible with an MFEs that depends on `^18.2.0`, and incompatible with an MFE that depends on `~18.2.0`.
+
+By default, MFEs and hosts share the following dependencies (see [here](https://github.com/search?q=repo%3Aservicetitan%2Fuikit+getDefaultSharedDependencies&type=code) for the most up-to-date list):
+
+- @servicetitan/anvil2
+- @servicetitan/design-system
+- classnames
+- formstate
+- mobx
+- mobx-react
+- mobx-utils
+- react
+- react-dom
+
+:::info
+MFE's are not required to use all the default dependencies; `startup` and `Loader` ignore any that aren't used.
+:::
+
+To customize which dependencies are shared, set `cli.webpack.shared-dependencies` to an object that maps dependencies to `SharedDependencies.{name}`. By convention `{name}` is the camel-cased package name.
+
+- Use the special **defaults** key with the empty string to incorporate the default list.
+- To exclude a default dependency, map it to the empty string.
+
+## Adding a Shared Dependency
+
+To add a dependency, use the special **defaults** key to first include the defaults. For example, to add `lodash` as a shared dependency,
+
+```json title="package.json"
+{
+    "cli": {
+        "webpack": {
+            "shared-dependencies": {
+                "defaults": "", // add default list
+                "lodash": "SharedDependencies.Lodash" // add lodash
+            }
+        }
+    }
+}
+```
+
+:::caution
+When you add a shared dependency its code is completely omitted from the **light** bundle. The host must include and share the same dependency, else it will always use the MFE's **full** bundle.
+:::
+
+## Omitting a Default Dependency
+
+:::tip
+Because monorepos's hoist dependencies into the project's root `package.json`, if a default shared dependency exists in the root `package.json`, `startup` assumes it is used by the MFE.
+If the MFE doesn't actually use a hoisted dependency, customize its shared dependencies to omit it.
+:::
+
+To omit an default dependency, map it to the empty string. For example, to omit `@servicetitan/design-system`:
+
+```json title="package.json"
+{
+    "cli": {
+        "webpack": {
+            "shared-dependencies": {
+                "defaults": "", // add default list
+                "@servicetitan/design-system": "" // drop @servicetitan/design-system
+            }
+        }
+    }
+}
+```
+
+## Specifying All Dependencies
+
+To completely customize the list of shared dependencies, omit the **defaults** key. For example, to only share Anvil2 and React,
+
+```json title="package.json"
+{
+    "cli": {
+        "webpack": {
+            "shared-dependencies": {
+                "@servicetitan/anvil2": "SharedDependencies.ServiceTitan.Anvil2",
+                "react": "SharedDependencies.React",
+                "react-dom": "SharedDependencies.ReactDOM"
+            }
+        }
+    }
+}
+```
+
+[^headless]: `startup` can also created **headless** bundles for preloading configuration or setup information. Headless bundles never share dependencies with hosts. See [Headless Bundle](./developing/headless-bundle) for more information.

package/docs/microfrontends/troubleshooting.mdx

@@ -0,0 +1,55 @@
+---
+title: Troubleshooting
+---
+
+## Styled-components
+
+We advise against using `styled-components` in MFEs. If you do, you may encounter an issue where styles are not applied because they are not injected properly.
+To fix, use `StyleSheetManager` to inject the styles into the MFE's ShadowDOM. For example,
+
+```tsx
+import { useMFEMetadataContext } from '@servicetitan/web-components';
+import styled, { StyleSheetManager } from 'styled-components';
+
+const Title = styled.h1`
+    color: #bf4f74;
+`;
+
+export const MFETitle: FC = () => {
+    const { shadowRoot } = useMFEMetadataContext();
+    return (
+        <StyleSheetManager target={shadowRoot}>
+            <Title>MFE Title</Title>
+        </StyleSheetManager>
+    );
+};
+```
+
+For styled components inside portalled elements (e.g., Popover), use `StyleSheetManager` to inject the styles into the MFE's portal ShadowDOM. For example,
+
+```tsx
+import { Popover } from '@servicetitan/anvil2';
+import { useMFEMetadataContext } from '@servicetitan/web-components';
+import styled, { StyleSheetManager } from 'styled-components';
+
+const PopoverTitle = styled.h2`
+    color: #bf4f75;
+`;
+
+export const MFEPopover: FC = () => {
+    const { portalShadowRoot } = useMFEMetadataContext();
+
+    return (
+        <Popover>
+            <Popover.Button>Click me!</Popover.Button>
+            <Popover.Content>
+                <StyleSheetManager target={portalShadowRoot}>
+                    <PopoverTitle>Title</PopoverTitle>
+                </StyleSheetManager>
+            </Popover.Content>
+        </Popover>
+    );
+};
+```
+
+See [useMFEMetadataContext](../web-components/use-mfe-metadata-context) for more information about accessing an MFE's ShadowDOM elements.