@servicetitan/docs-uikit 31.5.1 → 31.6.0

package/docs/BREAKING_CHANGES.mdx

@@ -63,14 +63,13 @@ title: BREAKING CHANGES
 
 ### [@servicetitan/ajax-handlers](./ajax-handlers)
 
-- Changed [**withMicroservice**](./ajax-handlers#parameters) arguments to a single options object.
+- Changed [**withMicroservice**](./ajax-handlers/with-microservice#parameters) arguments to a single options object.
 
 ## v24.0.0
 
 ### [@servicetitan/startup](./startup)
 
 - Upgraded **Typescript** from v4 to v5, which adds correctness improvements that will reveal previously undetected ambiguities. In particular,
-
     - Type checks for enums are stricter because all **enum** values get their own type
     - **string** and **boolean** values aren't implicitly converted to numbers. Use the `+` operator to explicitly convert values to numbers in mathematical expressions. (e.g., `return +str > 42;`)
 

package/docs/ajax-handlers/ajax-handlers.mdx

@@ -0,0 +1,12 @@
+---
+title: AJAX Handlers
+---
+
+#### [CHANGELOG (@servicetitan/ajax-handlers)](https://github.com/servicetitan/uikit/blob/master/packages/ajax-handlers/CHANGELOG.md)
+
+`@servicetitan/ajax-handlers` provides utilities for handling AJAX requests, authentication, and response processing in ServiceTitan applications. It includes automatic date parsing, authentication wrappers for protected resources, and comprehensive error handling.
+
+## API
+
+- [withMicroservice](./with-microservice.mdx) - Use `withMicroservice` to wrap components and authenticate requests to protected resources with support for Bearer and Token Server authentication.
+- [initAjaxHandlersParseDates](./init-ajax-handlers-parse-dates.mdx) - Use `initAjaxHandlersParseDates` to automatically transform date strings in axios responses into JavaScript Date objects.

package/docs/ajax-handlers/init-ajax-handlers-parse-dates.mdx

@@ -0,0 +1,74 @@
+---
+title: initAjaxHandlersParseDates
+---
+
+`initAjaxHandlersParseDates` is a function that automatically transforms date strings in axios responses into JavaScript Date objects. This eliminates the need for manual date parsing throughout your application.
+
+## Usage
+
+Call this function once in your application's initialization code, typically before making any axios requests:
+
+```tsx
+import { initAjaxHandlersParseDates } from '@servicetitan/ajax-handlers';
+
+// Initialize date parsing for all axios responses
+initAjaxHandlersParseDates();
+```
+
+## How It Works
+
+The function adds a response transformer to the global axios defaults that:
+
+1. Automatically detects and parses date strings in response data
+2. Recursively traverses objects and arrays to find date strings
+3. Preserves other data types unchanged (including Blobs)
+4. Handles parsing errors gracefully by returning the original data
+
+## Supported Date Formats
+
+The parser recognizes two date formats commonly used in APIs:
+
+### ISO 8601 Format
+
+Supports standard ISO date strings with optional time zones and milliseconds:
+
+- `2024-03-15T10:30:45Z`
+- `2024-03-15T10:30:45.123Z`
+- `2024-03-15T10:30:45+05:00`
+- `2024-03-15T10:30:45.789-08:00`
+
+### .NET JSON Date Format
+
+Supports the legacy .NET JSON date format:
+
+- `/Date(1710504645000)/`
+- `/Date(1710504645000-0800)/`
+- `/Date(-62135596800000)/` (negative timestamps for dates before 1970)
+
+## Example
+
+```tsx
+import axios from 'axios';
+import { initAjaxHandlersParseDates } from '@servicetitan/ajax-handlers';
+
+// Initialize date parsing once
+initAjaxHandlersParseDates();
+
+// Now all axios responses will have dates automatically parsed
+const response = await axios.get('/api/users/123');
+
+// response.data might look like:
+// {
+//   id: 123,
+//   name: 'John Doe',
+//   createdAt: Date object (not a string!),
+//   lastLogin: Date object (not a string!),
+//   metadata: {
+//     updatedAt: Date object (not a string!)
+//   }
+// }
+
+// You can immediately use Date methods
+console.log(response.data.createdAt.getFullYear());
+console.log(response.data.lastLogin.toLocaleDateString());
+```

package/docs/{ajax-handlers.mdx → ajax-handlers/with-microservice.mdx}

@@ -1,15 +1,11 @@
 ---
-title: AJAX Handlers
+title: withMicroservice
 ---
 
-#### [CHANGELOG (@servicetitan/ajax-handlers)](https://github.com/servicetitan/uikit/blob/master/packages/ajax-handlers/CHANGELOG.md)
-
-## withMicroservice
-
 `withMicroservice` is a higher-order function that wraps a component and authenticates
 its requests to protected resources.
 
-### Usage
+## Usage
 
 The best way to use `withMicroservice` is to wrap the component in the ES module body. E.g.,
 
@@ -54,7 +50,7 @@ const App = () => {
 }
 ```
 
-### Parameters
+## Parameters
 
 `withMicroservice` accepts an object with the following properties:
 
@@ -70,27 +66,27 @@ const App = () => {
 | `preAuthenticateCallback` | `(error?: any) => void`             | (optional) callback to call after pre-authentication succeeds or fails. If pre-authentication fails, the error is passed to the first parameter of the callback.                      |
 | `tokens`                  | `Symbol[]`                          | (optional) symbols to use to provide `baseURL` to autogenerated API services and child components                                                                                     |
 
-#### authAdapter{#auth-adapter}
+### authAdapter{#auth-adapter}
 
 Use `authAdapter` to select the authentication scheme. One of,
 
-| Value        | Description                                                                                                                                       |
-| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
-| "bearer"     | **Bearer** authentication sends the bearer token returned by `authURL` in the **Authorization** header of requests. Uses BearerTokenAuth adapter. |
-| "token"      | **Token** authentication uses the Token Server's "silent login" protocol to add secure cookies to requests. Uses TokenServerAuth adapter.         |
+| Value                                               | Description                                                                                                                                       |
+| :-------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
+| "bearer"                                            | **Bearer** authentication sends the bearer token returned by `authURL` in the **Authorization** header of requests. Uses BearerTokenAuth adapter. |
+| "token"                                             | **Token** authentication uses the Token Server's "silent login" protocol to add secure cookies to requests. Uses TokenServerAuth adapter.         |
 | `(context: WithMicroserviceContext) => AuthAdapter` | Custom authentication uses the adapter returned by a function to decorate requests.                                                               |
 
 See [Authentication Adapters](#authentication-adapters) for more information.
 
-#### authUrl
+### authUrl
 
 The authentication endpoint for protected resources.
 
--   For **Bearer** authentication, this is the endpoint that returns the bearer token to send in **Authorization** headers. Defaults to `${baseURL}/auth`.
+- For **Bearer** authentication, this is the endpoint that returns the bearer token to send in **Authorization** headers. Defaults to `${baseURL}/auth`.
 
--   For **Token server** authentication, this is the "silent login" endpoint. Defaults to `${baseURL}/bff/silent-login`.
+- For **Token server** authentication, this is the "silent login" endpoint. Defaults to `${baseURL}/bff/silent-login`.
 
-#### preAuthenticate{#pre-authenticate}
+### preAuthenticate{#pre-authenticate}
 
 Controls when authentication happens:
 
@@ -101,9 +97,9 @@ Controls when authentication happens:
 
 When using Token Server authentication, authentication is always performed after the component is loaded and this value is ignored.
 
-#### tokens
+### tokens
 
-The main purpose of `tokens` is to [provide](./react-ioc#provide) the `baseURL` to autogenerated API services.
+The main purpose of `tokens` is to [provide](../react-ioc#provide) the `baseURL` to autogenerated API services.
 For example,
 
 ```tsx
@@ -138,11 +134,11 @@ const Component = () => {
 }
 ```
 
-### Authentication Adapters{#authentication-adapters}
+## Authentication Adapters{#authentication-adapters}
 
 `withMicroservice` uses authentication adapters in order to perform authentication in different ways depending on your needs.
 
-#### BearerTokenAuth
+### BearerTokenAuth
 
 The default adapter is the `BearerTokenAuth` adapter. When authentication occurs, a request is sent to the `authURL` in order to retrieve a token. Then any requests made using the `baseURL` will add the `Authorization: Bearer ...` header with the stored token.
 
@@ -156,7 +152,7 @@ const App = withMicroservice({
 });
 ```
 
-#### TokenServerAuth{#token-server-auth}
+### TokenServerAuth{#token-server-auth}
 
 The `TokenServerAuth` adapter allows you to authenticate with a backend that is using the `ServiceTitan.Ium.Bff` NuGet package ([see TokenServer documentation for details](/docs/projects/ium/tokenserver-new-app-integration/)).
 
@@ -177,8 +173,8 @@ const App = withMicroservice({
 ```tsx title="Custom adapter"
 const options: TokenServerAuthOptions = {
     authInfoURL: '/custom/authinfo',
-    onError: (defaultErrorHandler) => {
-        console.error('There was an error');
+    onError: (defaultErrorHandler, error) => {
+        console.error(error, error.data);
         defaultErrorHandler();
     },
 };
@@ -189,12 +185,20 @@ const App = withMicroservice({
 });
 ```
 
-##### TokenServerAuthOptions
-| Name          | Type                                         | Description                                                                                                                                                                                  |
-| :------------ | :------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `authInfoURL` | `string`                                     | (optional) URL to fetch authentication parameters from. Defaults to `'/bff/authinfo'`.                                                                                                       |
-| `onError`     | `(defaultErrorHandler: () => void) => void;` | (optional) Callback to call when an error occurs during authentication. Defaults to reloading the page a maximum of 1 time. First parameter is a function to call the default error handler. |
+#### TokenServerAuthOptions
+
+| Name          | Type                                                       | Description                                                                                                                 |
+| :------------ | :--------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------- |
+| `authInfoURL` | `string`                                                   | (optional) URL to fetch authentication parameters from. Defaults to `'/bff/authinfo'`.                                      |
+| `onError`     | `(defaultErrorHandler: () => void, error: Error) => void;` | (optional) Callback to call when an error occurs during authentication. Defaults to reloading the page a maximum of 1 time. |
+
+The `onError` callback is passed the following arguments:
+
+| Name                  | Type       | Description                                                                                        |
+| :-------------------- | :--------- | :------------------------------------------------------------------------------------------------- |
+| `defaultErrorHandler` | `Function` | The default error handler.                                                                         |
+| `error`               | `Error`    | An error object with a `data` property that contains the data associated with the failure, if any. |
 
-### Authorization
+## Authorization
 
 `withMicroservice` currently only assists with performing authentication for requests of protected resources. There are currently no plans to implement authorization until we see concrete Token Server usage examples by product teams. If you find that having any sort of implementation for authorization would be helpful, especially in regards to Token Server implementation, please bring any ideas or discussions to the Frontend Platform team's attention so that we can create a platform solution.

package/docs/datadog-rum.mdx

@@ -0,0 +1,133 @@
+---
+title: DataDog RUM
+---
+
+#### [CHANGELOG (@servicetitan/datadog-rum)](https://github.com/servicetitan/uikit/blob/master/packages/datadog-rum/CHANGELOG.md)
+
+[`@servicetitan/datadog-rum`](https://github.com/servicetitan/uikit/tree/master/packages/datadog-rum) helps configure DataDog RUM JS SDK in standalone applications. It enriches RUM events with information useful for application and MFE monitoring, and troubleshooting.
+
+## Configuration snippet
+
+```tsx
+import { beforeSend, DatadogProvider } from '@servicetitan/datadog-rum';
+import { datadogRum } from '@datadog/browser-rum';
+
+const isEnabled = /.*go\d*\.servicetitan\.com/.test(window.location.hostname);
+
+if (isEnabled) {
+    datadogRum.init({
+        applicationId: '<APPLICATION_ID>',
+        clientToken: '<CLIENT_TOKEN>',
+        site: 'datadoghq.com',
+        service: '<SERVICE_NAME>',
+        env: '<ENV_NAME>',
+        version: '<APPLICATION_VERSION>',
+        sessionSampleRate: 100,
+        sessionReplaySampleRate: 0,
+        defaultPrivacyLevel: 'mask-user-input',
+        beforeSend: beforeSend(),
+    });
+}
+
+const Root = () => {
+    const user = useCurrentUser(); // application-specific hook that identifies the user
+
+    return (
+        <DatadogProvider isEnabled={isEnabled} user={user}>
+            <Application />
+        </DatadogProvider>
+    );
+};
+```
+
+## DatadogProvider
+
+`DatadogProvider` is a higher-order component that supplies RUM SDK with:
+
+- Information about the user session
+- Sanitized view event names (`@view.name`) when hash-based routing is used
+
+### Usage
+
+Wrap your application with `DatadogProvider` close to the root. E.g.,
+
+```tsx
+import { DatadogProvider } from '@servicetitan/datadog-rum';
+
+const Root = () =>
+    return (
+        <DatadogProvider isEnabled={isEnabled} user={user}>
+            ...
+        </DatadogProvider>
+    );
+};
+```
+
+If your application uses hash-based routing, `DatadogProvider` should be placed inside `HashRouter`. E.g.,
+
+```tsx
+import { HashRouter } from 'react-router-dom';
+import { DatadogProvider } from '@servicetitan/datadog-rum';
+
+const Root = () => {
+    return (
+        <HashRouter>
+            <DatadogProvider isEnabled={isEnabled} user={user} options={{ hashRouting: true }}>
+                ...
+            </DatadogProvider>
+        </HashRouter>
+    );
+};
+```
+
+### Parameters
+
+| Name        | Type      | Description                                 |
+| :---------- | :-------- | :------------------------------------------ |
+| `isEnabled` | `boolean` | Enables DD RUM instrumentation              |
+| `user`      | `User`    | (optional) User session information         |
+| `options`   | `Options` | (optional) Additional configuration options |
+
+#### `User`
+
+| Name            | Type                           | Description                          |
+| :-------------- | :----------------------------- | :----------------------------------- |
+| `id`            | `string`                       | User ID                              |
+| `[key: string]` | `string \| number \| string[]` | (optional) Arbitrary user attributes |
+
+#### `Options`
+
+| Name          | Type      | Description                                 |
+| :------------ | :-------- | :------------------------------------------ |
+| `hashRouting` | `boolean` | Sanitizes view names for hash-based routing |
+
+## `beforeSend`
+
+`beforeSend` is a callback function for enriching RUM events. Supported functionality:
+
+- Adds MFE name and version for error and resource events coming from MFEs (`@error.service`, `@resource.service`, `@error.version`, and `@resource.version`)
+- Adds Cloudflare Ray ID for resource events (`@resource.cfRay`)
+
+### Usage
+
+```ts
+import { beforeSend } from '@servicetitan/datadog-rum';
+import { datadogRum } from '@datadog/browser-rum';
+
+const isEnabled = /.*go\d*\.servicetitan\.com/.test(window.location.hostname);
+
+if (isEnabled) {
+    datadogRum.init({
+        applicationId: '<APPLICATION_ID>',
+        clientToken: '<CLIENT_TOKEN>',
+        site: 'datadoghq.com',
+        service: '<SERVICE_NAME>',
+        env: '<ENV_NAME>',
+        version: '<APPLICATION_VERSION>',
+        sessionSampleRate: 100,
+        sessionReplaySampleRate: 0,
+        defaultPrivacyLevel: 'mask-user-input',
+        beforeSend: beforeSend(), // <--beforeSend() returns handler that enriches events
+    });
+}
+```

package/docs/startup/review.mdx

@@ -192,6 +192,32 @@ npm pkg set "main"="dist/index.js" -w packages/lib
 
 ---
 
+### require-all-react-dependencies
+
+Ensures that any package which depends on either `react` or `react-dom` explicitly lists both as dependencies.
+React and ReactDOM are tightly coupled and should always be paired together to avoid runtime issues.
+
+#### ✅ Autofix
+
+This rule supports autofix.
+It adds the missing `react` or `react-dom` dependency, using the same version that is already present. For example, given:
+
+```json title="package.json"
+{
+    "dependencies": {
+        "react": "^18.3.1"
+    }
+}
+```
+
+It runs:
+
+```sh
+npm pkg set dependencies["react-dom"]="^18.3.1"
+```
+
+---
+
 ### require-explicit-side-effects
 
 Warns if a package is missing the `sideEffects` property in its `package.json`.
@@ -290,6 +316,22 @@ It sets the version of each dependency to the [highest](#highest-versions) of th
 
 ---
 
+### require-one-react-version
+
+Ensures the same version of `react` and `react-dom` is used across the workspace.
+
+These two packages are fundamentally designed to work together, with `react-dom` relying heavily on the internal structures and mechanisms exposed by `react`.
+
+While React 17 introduced features for gradual upgrades and potentially using multiple React versions in specific scenarios, maintaining synchronized versions of `react` and `react-dom` is the recommended and safest practice to ensure compatibility and avoid unforeseen issues.
+
+#### ✅ Autofix
+
+This rule supports autofix.
+It sets `react` and `react-dom` to the most common version in the repo.
+If multiple versions tie for the most common, it uses the [highest](#highest-versions) version among the top contenders.
+
+---
+
 ### require-one-uikit-version
 
 Ensures the same version of related `uikit` packages is installed across the workspace.

package/docs/startup/test.mdx

@@ -2,10 +2,204 @@
 title: test
 ---
 
-Runs all existing tests in all packages.
+Runs your project's tests.
 
-To run tests a subset of tests is possible to pass paths to specific directories or test files as positional parameters.
+- Supports both Jest and Vitest.
+- Automatically selects the test runner based on your workspace configuration or the `--runner` option.
+- Handles runner-specific arguments and passes them through to the underlying test tool.
+
+## Usage
+
+Run all tests with Jest (default):
+
+```sh
+npx startup test
+```
+
+Run all tests with Vitest:
+
+```sh
+npx startup test --runner vitest
+```
+
+:::tip
+Use the double-dash (--) separator to pass arguments to an `npm` script.
+This separator indicates that any arguments following it should be passed directly to the script being executed, rather than being interpreted by `npm` itself.
+For example, given the standard `startup test` script:
+
+```json
+{
+    "test": "npx startup test"
+}
+```
+
+Running,
+
+```sh
+npm run test -- --runner vitest
+```
+
+Executes,
+
+```sh
+npx startup test --runner vitest
+```
+
+:::
+
+## Running Specific Tests
+
+To run specific tests, pass their file names or paths as additional arguments.
+This works just like running Jest and Vitest directly, simply specify the file(s) you want to test:
+
+### Examples
+
+Run a specific test with Jest (default):
+
+```sh
+npx startup test app.test.tsx
+```
+
+Run a specific test with Vitest:
+
+```sh
+npx startup test --runner vitest app.test.tsx
+```
+
+## Using Jest
+
+The `startup test` command uses the Jest test runner by default.
+
+### Configuration
+
+The Jest runner provides a default, built-in configuration optimized for ServiceTitan workspaces.
+
+You can override the defaults by specifying [Jest options](https://jestjs.io/docs/configuration) in your workspace `package.json` under the `"cli.jest"` key (the `"cli.test"` key also works, for backward compatibility). You can also use a standard Jest config file (such as `jest.config.js`) to override defaults.
+
+Any options passed directly via the command line (e.g., `npx startup test --coverage`) take the highest precedence.
+
+:::caution
+If your project includes a standard Jest config file and also specifies Jest options in the workspace `package.json`, ensure that the configurations are mutually exclusive.
+To avoid confusing or unexpected behavior, do not specify the same setting in both locations.
+:::
+
+### Examples
+
+Use the workspace `package.json` to set up code that runs before each test file is executed:
+
+```json title="package.json"
+{
+    "cli": {
+        "jest": {
+            "setupFilesAfterEnv": ["<rootDir>/jest.setup.ts"]
+        }
+    }
+}
+```
+
+:::note
+For backward compatibility, you may also use the `ci.test` key:
+:::
+
+---
+
+Use `jest.config.js` to increase Jest's `testTimeout` on Windows:
+
+```js title="jest.config.js"
+module.exports = {
+    testTimeout: process.platform === 'win32' ? 60 * 1000 : undefined, // increase timeout on Windows
+};
+```
+
+---
+
+Use the command line to collect test coverage:
+
+```sh
+npx startup test --coverage
+```
+
+Use the command line to enable Jest's watch mode:
+
+```sh
+npx startup test --watch
+```
+
+## Using Vitest
+
+✨ New in **v31.6.0** ✨
+
+You can change the default test runner to `vitest` in your workspace's `package.json`:
+
+```json title="package.json"
+{
+    "cli": {
+        "testRunner": "vitest"
+    }
+}
+```
+
+Or override it per invocation with the `--runner` option.
+
+### Configuration
+
+The Vitest runner uses a layered configuration approach to provide sensible defaults while allowing full customization.
+
+- Uses the default, built-in configuration as a base.
+- Applies workspace overrides from `package.json`.
+- Applies overrides from your Vitest config file.
+- Applies command line options last.
+
+1. **Default Configuration:**  
+   The runner starts with a built-in default configuration optimized for ServiceTitan workspaces. This includes sensible coverage settings, the environment (`jsdom`), file exclusions, and more.
+
+2. **Workspace Configuration:**  
+   You can override defaults by specifying [Vitest options](https://vitest.dev/config) in your workspace `package.json` under the `"cli.vitest"` key.
+
+3. **Vitest Config File:**  
+   If your project includes a standard Vitest config file (such as `vitest.config.ts` or `vite.config.ts`), its settings will override both the defaults and workspace configuration.
+
+4. **Command Line Arguments:**  
+   Any options passed directly via the command line (e.g., `npx startup test --runner vitest --coverage`) take highest precedence and override all previous configuration layers.
+
+### Examples
+
+Use workspace `package.json` to make `vitest` APIs available [globally](https://vitest.dev/config/#globals) like Jest:
+
+```json title="package.json"
+{
+    "cli": {
+        "vitest": {
+            "globals": true
+        }
+    }
+}
+```
+
+---
+
+Use Vitest config file to disable watch mode:
+
+```ts title="vitest.config.mts"
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+    test: {
+        watch: false,
+    },
+});
+```
+
+---
+
+Use the command line to disable watch mode:
+
+```sh
+npx startup test --runner vitest --run
+```
+
+Use the command line to collect code coverage:
 
 ```sh
-npx startup test -- packages/desktop/app/modules/inventory/
+npx startup test --runner vitest --coverage
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@servicetitan/docs-uikit",
-    "version": "31.5.1",
+    "version": "31.6.0",
     "description": "",
     "repository": {
         "type": "git",
@@ -16,5 +16,5 @@
     "cli": {
         "webpack": false
     },
-    "gitHead": "8eb35a6e98b9e3cb3b18b452ce9ba76f278d0e61"
+    "gitHead": "533bcbd267e11c88700b29f539ca1cb5de6440ae"
 }