@servicetitan/docs-uikit 28.1.0 → 28.2.0

package/docs/launchdarkly-service.mdx

@@ -0,0 +1,142 @@
+---
+title: LaunchDarkly Service
+---
+
+#### [CHANGELOG (@servicetitan/launchdarkly-service)](https://github.com/servicetitan/uikit/blob/master/packages/launchdarkly-service/CHANGELOG.md)
+
+ServiceTitan's LaunchDarkly platform has multiple "projects" (e.g., Dispatch Center, Contact Center, FleetPro),
+each with its own set of feature flags and client-side IDs that authorize connections.
+
+LaunchDarkly's SDKs require applications to create a separate client connection to the LaunchDarkly backend for each project.
+However, if applications and MFEs create multiple, independent connections to the same LaunchDarkly project, it can degrade performance
+and cause the uikit to behave inconsistently. It also harms performance to teardown and recreate connections each time an
+MFE is unloaded and reloaded.
+
+To prevent these issues **@servicetitan/launchdarkly-service** implements a coordinated approach for creating
+and reusing client connections for LaunchDarkly projects.
+Instead of using **LDProvider**, **withLDProvider** or **withAsyncLDProvider** from the LaunchDarkly React SDK, use **LDProvider** from **@servicetitan/launchdarkly-service**.
+
+## Usage
+
+**@servicetitan/launchdarkly-service** allows host applications and MFEs to share and reuse connections to LaunchDarkly. It ensures that only one connection is created for each LaunchDarkly project. To use:
+
+1. Wrap the MFE application (or code within the host) with [`LDProvider`](#ldprovider) from `@servicetitan/launchdarkly-service`.
+2. Wrap the host application with [`LDServiceProvider`](#ldserviceprovider) (if applicable).
+3. Use the standard [hooks](https://docs.launchdarkly.com/sdk/client-side/react/react-web#hooks) from the [launchdarkly-react-client-sdk](https://docs.launchdarkly.com/sdk/client-side/react/react-web) to access feature flags and the client object.
+
+## API
+
+### LDProvider
+
+`LDProvider` provides LaunchDarkly feature flags within hosts and MFEs.
+It ensures that hosts and MFEs share one client connection to each LaunchDarkly project (as identified by the client-side ID).
+
+#### Props
+
+| Name                    | Type      | Description                                                                                                                                                                                                                                                             |
+| :---------------------- | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `clientSideID`          | `string`  | The client-side ID that authorizes the client to connect to a particular LaunchDarkly project. The [getValueForEnvironment](./web-components#getvalueforenvironment) helper provides a convenient way to map Monolith environments to the corresponding client-side ID. |
+| `projectName`           | `string`  | The name of the LaunchDarkly project, for logs and error messages.                                                                                                                                                                                                      |
+| `context`               | `object`  | (Optional) Context for targeting rules. Defaults to anonymous user. Use LaunchDarkly's [`identify`](https://docs.launchdarkly.com/sdk/features/identify) method to change the context after initialization.                                                             |
+| `waitForInitialization` | `boolean` | (Optional) Whether or not to wait until flags values are available before rendering children. Defaults to `true`                                                                                                                                                        |
+
+:::caution
+When a `context` is provided, only the initial value takes affect. Subsequent calls with the same client-side ID reuse the client that was created with the initial context.
+
+This is typically only a problem when different code paths call `LDProvider` with different contexts. To avoid this, create a standard `LDProvider` wrapper for each project (see example below).
+If that isn't practical, you can use [`getContext`](https://launchdarkly.github.io/js-client-sdk/interfaces/LDClient.html#getContext) and [`identify`](https://launchdarkly.github.io/js-client-sdk/interfaces/LDClient.html#identify) to fetch and amend the active context.
+:::
+
+:::caution
+When `waitForInitialization` is set to false, the UI could render immediately, with no flags,
+and the LaunchDarkly SDK won't automatically re-render components when the flags become available.
+If this is a problem, you can [subscribe to flag changes](https://docs.launchdarkly.com/sdk/features/flag-changes)
+and manually trigger updates.
+:::
+
+#### Examples
+
+For example, to provide feature flags for the TitanAdvisor project, create a `TitanAdvisorLDProvider` component that wraps its children with the appropriate `LDProvider`:
+
+```tsx title="titan-advisor-ld-provider.tsx"
+import { LDProvider } from '@servicetitan/launchdarkly-service';
+import { getValueForEnvironment } from '@servicetitan/web-components'
+import { FC, PropsWithChildren, useMemo } from 'react';
+
+export const TitanAdvisorLDProvider: FC<PropsWithChildren> = ({ children }) => {
+    const clientSideID = useMemo(() => {
+        return getValueForEnvironment({
+            dev: '669fe6e5cc97eb103be7a620',
+            go: '669fe5bff00a0c0fa60b25e4',
+            next: '669fe5bff00a0c0fa60b25e4' // using 'go' here, but could also be 'qa'
+            qa: '669fe6d6f00a0c0fa60b2721',
+            stage: '669fe65979abf310b860236e',
+        });
+    }, []);
+
+    if (!clientSideID) {
+        // This only happens in the "test" environment, because "test" was omitted above.
+        return children;
+    }
+
+    return (
+        <LDProvider clientSideID={clientSideID} projectName="TitanAdvisor">
+            {children}
+        </LDProvider>
+    );
+};
+```
+
+Then, to provide those flags globally to the entire TitanAdvisor MFE, wrap the MFE's `App`:
+
+```tsx title="app.tsx"
+import { FC, StrictMode } from 'react';
+
+import { TitanAdvisorLDProvider } from './titan-advisor-ld-provider';
+
+export const App: FC = () => {
+    return (
+        <StrictMode>
+            <TitanAdvisorLDProvider>
+                {...}
+            </TitanAdvisorLDProvider>
+        </StrictMode>
+    );
+};
+```
+
+Or, to provide TitanAdvisor flags to a component in the Monolith, wrap the component:
+
+```tsx
+// Rename original Component to ComponentUnwrapped
+const ComponentUnwrapped: FC<ComponentProps> = props => {};
+
+// Export wrapped Component
+export const Component: FC<ComponentProps> = props => {
+    return (
+        <TitanAdvisorLDProvider>
+            <ComponentUnwrapped {...props} />
+        </TitanAdvisorLDProvider>
+    );
+};
+```
+
+### LDServiceProvider
+
+`LDServiceProvider` enables sharing and reusing LaunchDarkly clients outside the Monolith.
+Simply wrap the host with `LDServiceProvider` to ensure that it and embedded MFEs use a single connection for each LaunchDarkly project.
+
+```tsx
+import { FC, StrictMode } from 'react';
+import { LogService } from '@servicetitan/launchdarkly-service';
+
+export const HostApp: FC = () => {
+    return(
+        <StrictMode>
+            <LDServiceProvider>
+                {...}
+            </LDServiceProvider>
+        </StrictMode>
+    );
+};
+```

package/docs/log-service.mdx

@@ -90,7 +90,7 @@ export const App: FC = () => {
         <StrictMode>
             <LogService>
                 {...}
-            <LogService>
+            </LogService>
         </StrictMode>
     );
 };

package/docs/startup.mdx

@@ -357,6 +357,15 @@ Or you can set an object with detailed configs:
     }
 }
 ```
+
+Or you can use relative path to a file that exports an object with detailed configs (useful to share configs between multiple MFEs in repo):
+```json title="package.json"
+{
+    "cli": {
+        "web-component": "../../config/web-component.js"
+    }
+}
+```
 ###### Web component config options
 
 -   `branches` - Set git branch specific configs, used for publishing. See [Branch configs](#branch-configs).

package/docs/web-components.mdx

@@ -153,6 +153,59 @@ The following metadata about an MFE is available from `useMFEMetadataContext` ho
 | `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 Monolith 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<Environment,  string>` | Object that maps each environment to a value (see below).                                  |
+| `defaultEnvironment` | `Environment`                  | The environment to use when the current environment is not recognized. 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 (e.g., `localhost`)                     |
+| **go**      | Production environment                                          |
+| **qa**      | QA environment                                                  |
+| **next**    | Next environment                                                |
+| **stage**   | Staging environment                                             |
+| **test**    | Unit test environment (i.e., `process.env.NODE_ENV === 'test'`) |
+
+#### 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.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@servicetitan/docs-uikit",
-    "version": "28.1.0",
+    "version": "28.2.0",
     "description": "",
     "repository": {
         "type": "git",
@@ -16,5 +16,5 @@
     "cli": {
         "webpack": false
     },
-    "gitHead": "27d173aad0e016014bed59385886d0fd7ca3fb17"
+    "gitHead": "df48bdf4994bce3971c7e4f099eeb11ebb4945e6"
 }