@servicetitan/docs-uikit 28.1.1 → 28.3.0

package/docs/launchdarkly-service.mdx

@@ -0,0 +1,336 @@
+---
+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 UI 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)
+and automatically [provides a store](#use-flags-in-mobx-store) that allows flag values to be used in MobX stores.
+
+#### 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.
+:::
+
+:::note
+When `waitForInitialization` is set to false, `LDProvider` renders children immediately, possibly with no flag values,
+then automatically re-renders when the flags become available.
+:::
+
+#### 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>
+    );
+};
+```
+
+### FeatureFlagStore
+
+`LDProvider` automatically provides a `FeatureFlagStore` that allows you to access
+feature flags in MobX stores.
+To use [@inject](./react-ioc#inject) where needed.
+
+#### Props
+
+| Name    | Type        | Description                     |
+| :------ | :---------- | :------------------------------ |
+| `flags` | `LDFlagSet` | The LaunchDarkly feature flags. |
+
+#### Example
+
+```tsx
+import { FeatureFlagStore } from '@servicetitan/launchdarkly-service';
+
+class ConsumerStore {
+    constructor(@inject(FeatureFlagStore) private readonly featureFlagStore: FeatureFlagStore) {
+        // this.featureFlagStore.flags contains feature flags
+    }
+}
+```
+
+### WithFeatureFlag
+
+`WithFeatureFlag` conditionally renders content depending on the value of a feature flag.
+
+#### Props
+
+| Name      | Type                  | Description                                                                                                                         |
+| :-------- | :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------- |
+| `flagKey` | `string`              | The feature flag's key. To type check `flagKey`, pass a type argument that defines the flag set (see [below](#type-check-flag-key)) |
+| `on`      | `React.ComponentType` | (Optional) Component to render when the flag is turned on. Defaults to `children` prop.                                             |
+| `off`     | `React.ComponentType` | (Optional) Component to render when the flag is turned off. Defaults to `null`.                                                     |
+| `value`   | `LDFlagValue`         | (Optional) Flag value that indicates the flag is turned on. Defaults to treating any truthy value as "on".                          |
+
+#### Examples
+
+Render children when flag is turned on:
+
+```tsx
+<WithFeatureFlag flagKey={flagKey}>
+    <Text>Flag is ON</Text>
+</WithFeatureFlag>
+```
+
+Render children when flag has specific value:
+
+```tsx
+<WithFeatureFlag flagKey={flagKey} value={false}>
+    <Text>Flag is false</Text>
+</WithFeatureFlag>
+```
+
+Render children when flag is on, and render other component when flag is turned off:
+
+```tsx
+<WithFeatureFlag flagKey={flagKey} off={ComponentV1}>
+    <ComponentV2 />
+</WithFeatureFlag>
+```
+
+Render component when flag is on, and render other component when flag is turned off:
+
+```tsx
+<WithFeatureFlag flagKey={flagKey} on={ComponentV2} off={ComponentV1} />
+
+<WithFeatureFlag flagKey={flagKey} on={() => 'Flag is ON'} off={() => 'Flag is OFF'} />
+```
+
+## Examples
+
+### Using flag values in React component
+
+Use the `useFlags` hook from the LaunchDarkly React SDK to access flags in React components. E.g.,
+
+```tsx
+import { useFlags } from 'launchdarkly-react-client-sdk';
+
+export const Component: FC = () => {
+    const { enableRedesign } = useFlags();
+    return enableRedesign ? <NewDesign /> : <OldDesign />;
+};
+```
+
+Or, use this package's [WithFeatureFlag](#withfeatureflag) helper:
+
+```tsx
+import { WithFeatureFlag } from '@servicetitan/launchdarkly-service';
+
+export const Component: FC = () => (
+    <WithFeatureFlag flagKey="enableRedesign" on={NewDesign} off={OldDesign} />
+);
+```
+
+### Using flag values in MobX store {#use-flags-in-mobx-store}
+
+To use flag values in MobX stores, inject the [FeatureFlagStore](#featureflagstore) provided by `LDProvider`.
+For example,
+
+```tsx
+import { FeatureFlagStore } from '@servicetitan/launchdarkly-service';
+
+@injectable()
+export class DataStore extends Store {
+    constructor(@inject(FeatureFlagStore) private readonly featureFlagStore: FeatureFlagStore) {
+        // Use this.featureFlagStore.flags to access feature flags
+        if (this.featureFlagStore.flags.enableDataV2) {
+            this.initializeDataV2();
+        } else {
+            this.initializeData();
+        }
+    }
+}
+```
+
+### Type checking WithFeatureFlag key {#type-check-flag-key}
+
+To type check the `flagKey` passed to `WithFeatureFlag`, pass a type argument that defines the flag set.
+For example,
+
+```tsx title='fleet-flag-set.ts'
+export interface FleetFlagSet {
+    enablePermissions: boolean;
+    enableBreadcrumbPage: boolean;
+    enableAlertsRedesign: boolean;
+}
+```
+
+```tsx
+<WithFeatureFlag<FleetFlagSet> flagKey={flagKey} /> // Enforces that flagKey is in FleetFlagSet
+```
+
+Or, create a custom wrapper that does this automatically. For example,
+
+```tsx title='with-fleet-feature-flag.tsx'
+import { WithFeatureFlag, WithFeatureFlagProps } from '@servicetitan/launchdarkly-service';
+import { FleetFlagSet } from './fleet-flag-set';
+
+export const WithFleetFeatureFlag = <T extends keyof FleetFlagSet>(
+    props: WithFeatureFlagProps<FleetFlagSet, T>
+) => <WithFeatureFlag<FleetFlagSet, T> {...props} />;
+```
+
+```tsx
+<WithFleetFeatureFlag flagKey={flagKey} /> // Enforces that flagKey is in FleetFlagSet
+```
+
+### Type checking WithFeatureFlag value
+
+To type check the `value` passed to `WithFeatureFlag`, use the `createFlagKeys` helper.
+It returns an object with keys that enable type checking against the passed `value`. For example,
+
+```tsx title='fleet-flag-set.ts'
+import { createFlagKeys } from '@servicetitan/launchdarkly-service';
+
+export interface FleetFlagSet {
+    enablePermissions: boolean;
+    enableBreadcrumbPage: boolean;
+    enableAlertsRedesign: boolean;
+    triStateFlag: 0 | 1 | 2; // flag has non-boolean value
+}
+
+export const FleetFlagKeys = createFlagKeys<FleetFlagSet>( // generates type-aware keys
+    'enablePermissions',
+    'enableBreadcrumbPage',
+    'enableAlertsRedesign',
+    'triStateFlag'
+);
+```
+
+```tsx
+// Use generated key to enforce that value is correct type, in this case, 0, 1 or 2
+<WithFeatureFlag flagKey={FleetFlagKeys.triStateFlag} value={2} />
+
+// Use generated key to type check value passed to custom wrapper
+<WithFleetFeatureFlag flagKey={FleetFlagKeys.triStateFlag} value={2} />
+```
+
+### Type checking FeatureFlagStore
+
+To type check `FeatureFlagStore` keys, pass a type argument that defines the flag set.
+For example,
+
+```tsx title='consumer-store.ts'
+class ConsumerStore {
+    constructor(
+        @inject(FeatureFlagStore)
+        // Establishes that type of this.featureFlagStore.flags is FleetFlagSet
+        private readonly featureFlagStore: FeatureFlagStore<FleetFlagSet>
+    ) {}
+}
+```

package/docs/log-service.mdx

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

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.1",
+    "version": "28.3.0",
     "description": "",
     "repository": {
         "type": "git",
@@ -16,5 +16,5 @@
     "cli": {
         "webpack": false
     },
-    "gitHead": "35c714f4eaf0ba60dd6fa3fc583f0283edfb4a44"
+    "gitHead": "63ce3ca18966fc5522a3b61df5e4c55f82b4272e"
 }