@servicetitan/docs-uikit 28.2.0 → 28.3.0

package/docs/launchdarkly-service.mdx

@@ -9,7 +9,7 @@ each with its own set of feature flags and client-side IDs that authorize connec
 
 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
+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
@@ -29,7 +29,8 @@ Instead of using **LDProvider**, **withLDProvider** or **withAsyncLDProvider** f
 ### 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).
+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
 
@@ -47,11 +48,9 @@ This is typically only a problem when different code paths call `LDProvider` wit
 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.
+:::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
@@ -140,3 +139,198 @@ export const HostApp: FC = () => {
     );
 };
 ```
+
+### 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/package.json

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