@servicetitan/docs-uikit 22.20.0 → 23.0.0

package/docs/eslint-config.mdx

@@ -2,8 +2,21 @@
 title: ESLint & Stylelint configurations
 ---
 
+import Admonition from '@theme/Admonition';
+import { VersionHistory, Changes } from '@site/src/components/version-history';
+
 `@servicetitan/eslint-config` and `@servicetitan/stylelint-config` packages contain core lint rule sets which should be used in ServiceTitan web projects.
 
+<VersionHistory>
+    <Changes forVersion="23.0.0">
+        <Admonition type="caution">
+            Upgrades <code>@typescript-eslint/eslint-plugin</code> from version v5.x to v6. Because
+            every new major version of <code>typescript-eslint</code> includes improvements and
+            changes to existing rules, expect to see new lint errors in your project.
+        </Admonition>
+    </Changes>
+</VersionHistory>
+
 ## Usage
 
 ### ESLint

package/docs/react-ioc.mdx

@@ -4,6 +4,28 @@ title: React IoC
 
 `@servicetitan/react-ioc` is an implementation of [InversifyJS](https://github.com/inversify/InversifyJS) for react applications, it uses Context API of React 16 to manage containers.
 
+import Admonition from '@theme/Admonition';
+import { VersionHistory, Changes } from '@site/src/components/version-history';
+
+<VersionHistory>
+    <Changes forVersion="v23.0.0">
+        <Admonition type="caution" title="Breaking changes">
+            <p>
+                Changed second argument of <code>provide</code> method to an object with
+                <code>loadingFallback</code> and <code>errorFallback</code> properties.
+            </p>
+            <p>
+                Renamed <code>fallback</code> property of the <code>Provider</code> component to{' '}
+                <code>loadingFallback</code> and added <code>errorFallback</code> property.
+            </p>
+            <p>
+                Removed ability to use <code>useValue</code> with <code>instances</code>.
+            </p>
+        </Admonition>
+        See <a href="https://github.com/servicetitan/uikit/releases/tag/v23.0.0">Release Notes</a>
+    </Changes>
+</VersionHistory>
+
 ## Features
 
 -   Supports hierarchical Dependency Injection
@@ -159,3 +181,45 @@ const App = provide({ singletons: [{ provide: LOGGER_TOKEN, useClass: Logger }]
     </ErrorBoundary>
 ));
 ```
+
+#### Reusing a service
+
+You can use the inherit option to reuse existing services that are already provided. In this case, service is only created if it is not already provided in a parent container.
+
+```tsx
+class SomeStore {}
+
+class SomeOtherStore {}
+
+const App = provide({
+    singletons: [
+        { provide: SomeStore, useClass: SomeOtherStore, inherit: true },
+        { provide: SomeOtherStore, inherit: true },
+    ],
+})(() => <div />);
+```
+
+#### Service initialization
+
+If a service inherits from Store, react-ioc calls the optional `initialize` method before rendering content and calls `dispose` after unbind. Also, you can pass a loading fallback that will be rendered during initialization.
+
+```tsx
+import { Spinner } from '@servicetitan/design-system';
+import { Store } from '@servicetitan/react-ioc';
+
+class SomeStore extends Store {
+    constructor() {
+        super();
+    }
+
+    async initialize() {
+        // do some initialization
+    }
+
+    dispose() {
+        // implement disposal
+    }
+}
+
+const App = provide({ singletons: [SomeStore] }, { loadingFallback: <Spinner /> })(() => <div />);
+```

package/docs/startup.mdx

@@ -5,7 +5,18 @@ title: Startup
 import Admonition from '@theme/Admonition';
 import { VersionHistory, Changes } from '@site/src/components/version-history';
 
+[@servicetitan/startup](https://github.com/servicetitan/uikit/tree/master/packages/startup) is a command-line interface (CLI) to create multi-package Lerna projects with the support of TypeScript Project References and React. It offers a modern build setup with no configuration.
+
 <VersionHistory>
+    <Changes forVersion="23.0.0">
+        <Admonition type="caution">
+            Upgraded <code>Jest</code> from version v27.x to v29.
+            The largest breaking change is that v29 changed the default snapshot format.
+            To update old snapshots, run <code>npm run test -- --updateSnapshot</code>.
+            <br/>
+            See <a href="https://jest-archive-august-2023.netlify.app/docs/28.x/upgrading-to-jest28">Upgrading from v27 to v28</a> and <a href="https://jestjs.io/docs/upgrading-to-jest29">Upgrading from v28 to v29</a> for a list changes.
+        </Admonition>
+    </Changes>
     <Changes forVersion="22.20.0">
         Added <code>--experimental-bundlers</code> option to <code>build</code> command
     </Changes>
@@ -20,13 +31,13 @@ import { VersionHistory, Changes } from '@site/src/components/version-history';
     </Changes>
     <Changes forVersion="v22.16.0">
         <Admonition type="warning" title="Deprecated">
-            This version contains a critical bug that was introduced in v22.15.0 and fixed in v22.17.0. Update to v22.17.0 or later as soon an possible.
+            This version contains a critical bug that was introduced in v22.15.0 and fixed in v22.17.0. Update to v22.17.0 or later as soon as possible.
         </Admonition>
         Added @servicetitan/testing-library to the <code>startup init</code> template
     </Changes>
     <Changes forVersion="v22.15.0">
         <Admonition type="warning" title="Deprecated">
-            This version contains a critical bug that was introduced in v22.15.0 and fixed in v22.17.0. Update to v22.17.0 or later as soon an possible.
+            This version contains a critical bug that was introduced in v22.15.0 and fixed in v22.17.0. Update to v22.17.0 or later as soon as possible.
         </Admonition>
         Runs all commands with 8GB of memory by default.
     </Changes>
@@ -75,8 +86,6 @@ import { VersionHistory, Changes } from '@site/src/components/version-history';
 
 </VersionHistory>
 
-[@servicetitan/startup](https://github.com/servicetitan/uikit/tree/master/packages/startup) is a command-line interface (CLI) to create multi-package Lerna projects with the support of TypeScript Project References and React. It offers a modern build setup with no configuration.
-
 ## Why use this package?
 
 #### Less to learn

package/docs/web-components.mdx

@@ -0,0 +1,230 @@
+---
+title: Web Components
+---
+
+import Admonition from '@theme/Admonition';
+import { VersionHistory, Changes } from '@site/src/components/version-history';
+
+<VersionHistory>
+    <Changes forVersion="v22.21.1">
+        Fixed a bug where the `Loader` component would error if an MFE's metadata.json contains a dependency of `web-components` with a version that is a semver range.
+    </Changes>
+    <Changes forVersion="v22.21.0">
+        <Admonition type="warning" title="Deprecated">
+            This version contains a critical bug that was introduced in v22.21.0 and fixed in v22.21.1. Update to v22.21.1 or later as soon as possible.
+        </Admonition>
+        Provided a more guaranteed check for an MFE's ability to re-render when passed MFE data changes.
+        Added context for MFEMetadata, which includes the shadowDom and portalShadowDom.
+    </Changes>
+    <Changes forVersion="v22.16.0">
+        Fixed Loader memory leaks.
+    </Changes>
+    <Changes forVersion="v22.12.0">
+        Support updating props passed to MFE via Loader.
+        Added context for accessing MFEData.
+    </Changes>
+    <Changes forVersion="v22.7.0">
+        Fixed disposing MFE when parent element has moved in DOM.
+    </Changes>
+    <Changes forVersion="v22.1.0">
+        Added EventBus support for sending payload with events.
+    </Changes>
+</VersionHistory>
+
+`@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: React.FC = () => {
+    ...
+    return (
+        ...
+        <Loader src="https://unpkg.servicetitan.com/{package_name}@{semver_range}" />
+        ...
+    );
+};
+```
+
+#### Props
+
+| Name              | Description                                                                                                                                         |
+| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src`             | path to an MFE root folder                                                                                                                          |
+| `fallbackSrc`     | optional alternative path to an MFE root folder (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 JSX element to render when the MFE is loading                                                                                              |
+| `errorFallback`   | optional JSX element to render when the MFE fails to load                                                                                           |
+| `className`       | additional CSS classes for the MFE web component element                                                                                            |
+
+#### Passing data from Host to MFE
+
+You can pass data from your host application to the MFE using the `data` prop of the `<Loader>` component. The data should be an object where keys are string and the values are any serializable data.
+
+We recommend memoizing your data before passing it to the `<Loader>` component in order to avoid potential performance issues with re-rendering and re-serializing that data.
+
+As a reminder, it should be clearly discouraged (or sometimes prohibited) to share data between the host and MFEs. MFEs should load the data they need instead of relying on the host to pass it, when possible.
+
+:::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.
+
+### 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 recieve.
+
+```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.
+
+| 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 |
+
+### 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.
+
+#### Subscription
+
+```tsx title="MFE"
+...
+
+import { useOptionalDependencies } from '@servicetitan/react-ioc';
+import { EVENT_BUS_TOKEN } from '@servicetitan/web-components';
+
+...
+
+export const Foo: FC = () => {
+    const [eventBus] = useOptionalDependencies(EVENT_BUS_TOKEN);
+
+    useEffect(() => {
+        const myCustomEventHandler = () => {
+            console.log('`my-custom-event` has been fired!');
+        };
+        eventBus?.on('my-custom-event', myCustomEventHandler);
+
+        return () => {
+            eventBus?.off('my-custom-event', myCustomEventHandler);
+        };
+    }, []);
+
+    ...
+};
+```
+
+#### Emitting
+
+```tsx title="host"
+...
+
+import { Loader, LoaderRef } from '@servicetitan/web-components';
+
+...
+
+export const Bar: FC = () => {
+    const ref = useRef<LoaderRef>(null);
+
+    useEffect(() => {
+        const id = setInterval(() => {
+            ref.current?.emit('my-custom-event');
+        }, 1000);
+
+        return () => {
+            clearInterval(id);
+        };
+    }, []);
+
+    ...
+
+    return (
+        ...
+        <Loader ref={ref} src="https://unpkg.servicetitan.com/@servicetitan/examples" />
+        ...
+    );
+};
+```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@servicetitan/docs-uikit",
-    "version": "22.20.0",
+    "version": "23.0.0",
     "description": "",
     "repository": {
         "type": "git",
@@ -16,5 +16,5 @@
     "cli": {
         "webpack": false
     },
-    "gitHead": "ec4a9c96e9927170b725720de33e97efed24c724"
+    "gitHead": "45876ed36415ad78d3ec4ef3783d6df1430504d3"
 }