@servicetitan/docs-uikit 30.3.1 → 31.1.0

package/docs/BREAKING_CHANGES.mdx

@@ -2,71 +2,77 @@
 title: BREAKING CHANGES
 ---
 
+## v31.0.0
+
+### [@servicetitan/startup](./startup)
+
+- Migrated to SWC for TypeScript compilation. See [Upgrading to @servicetitan/startup v31.x](/docs/frontend/upgrading-to-startup-v31) for guidance.
+
 ## v30.0.0
 
 ### [@servicetitan/startup](./startup)
 
--   Upgraded ESLint to v9.x and dropped support for legacy "eslintrc" configuration. See [Upgrading to ESLint v9.x](/docs/frontend/upgrading-to-eslint-v9) for guidance.
+- Upgraded ESLint to v9.x and dropped support for legacy "eslintrc" configuration. See [Upgrading to ESLint v9.x](/docs/frontend/upgrading-to-eslint-v9) for guidance.
 
 ### [@servicetitan/eslint-config](./eslint-config)
 
--   Dropped support for legacy "eslintrc" configuration
+- Dropped support for legacy "eslintrc" configuration
 
 ## v29.0.0
 
 ### [@servicetitan/startup](./startup)
 
--   Dropped support for Node 18.
-    Update Github workflows and Docker containers to use Node v20 or later, and bump the `engines.node` property in package.json files to >=20 or >=22.
+- Dropped support for Node 18.
+  Update Github workflows and Docker containers to use Node v20 or later, and bump the `engines.node` property in package.json files to >=20 or >=22.
 
--   Added safeguards to mfe-publish to avoid accidentally deleting production bundles
-    -    Changed `--clean` to never remove old versions that have a tag
-    -    Changed the default behavior of `--clean` to only remove old versions from the current branch. Use `--branch` to remove old versions from a different branch and use `--all` to remove old versions from all branches.
+- Added safeguards to mfe-publish to avoid accidentally deleting production bundles
+    - Changed `--clean` to never remove old versions that have a tag
+    - Changed the default behavior of `--clean` to only remove old versions from the current branch. Use `--branch` to remove old versions from a different branch and use `--all` to remove old versions from all branches.
 
 ## v28.0.0
 
 ### [@servicetitan/startup](./startup)
 
--   Changed the default [moduleResolution](https://www.typescriptlang.org/tsconfig/#moduleResolution) from `node` to `bundler` to support importing from `@servicetitan/anvil2/token`. CommonJS packages that require the previous value must override `moduleResolution` in the package's `tsconfig.json`.
+- Changed the default [moduleResolution](https://www.typescriptlang.org/tsconfig/#moduleResolution) from `node` to `bundler` to support importing from `@servicetitan/anvil2/token`. CommonJS packages that require the previous value must override `moduleResolution` in the package's `tsconfig.json`.
 
 ## v27.0.0
 
 ### [@servicetitan/startup](./startup)
 
--   Upgraded **prettier** from v2 to v3.
-    Beside the usual formatting changes, the default value for [**trailingComma**](https://prettier.io/docs/en/options.html#trailing-commas) changed from "es5" to "all".
-    To fix the issues, add `"trailingComma": "es5"` to the [prettier configuration](https://prettier.io/docs/en/configuration) then run `npx startup lint --fix` to fix new lint errors.
-    To prevent specific files from being reformatted, add them to [**.prettierignore**](https://prettier.io/docs/en/ignore.html).
+- Upgraded **prettier** from v2 to v3.
+  Beside the usual formatting changes, the default value for [**trailingComma**](https://prettier.io/docs/en/options.html#trailing-commas) changed from "es5" to "all".
+  To fix the issues, add `"trailingComma": "es5"` to the [prettier configuration](https://prettier.io/docs/en/configuration) then run `npx startup lint --fix` to fix new lint errors.
+  To prevent specific files from being reformatted, add them to [**.prettierignore**](https://prettier.io/docs/en/ignore.html).
 
 ## v26.0.0
 
 ### [@servicetitan/startup](./startup)
 
--   Upgraded **webpack-dev-server** from v3 to v5, which introduces many breaking changes to the configuration settings.
-    For a complete list see [v4 migration guide](https://github.com/webpack/webpack-dev-server/blob/master/migration-v4.md) and [v5 migration guide](https://github.com/webpack/webpack-dev-server/blob/master/migration-v5.md). Some common issues are:
-    -   **contentBase** and **watchContentBase** were removed; use **static**
-    -   **disableHostCheck** was removed; use `allowedHosts: 'all'`
-    -   **hotOnly** was removed; use `hot: 'only'`
-    -   **http2** and **https** were removed; use **server**
-    -   **injectClient** and **injectHot** were removed in favor of manual setup entries
-    -   **inline** was removed without replacement
-    -   **proxy** only accepts an array
-    -   **publicPath**, **stats** and **writeToDisk** were moved to **devMiddleware**
+- Upgraded **webpack-dev-server** from v3 to v5, which introduces many breaking changes to the configuration settings.
+  For a complete list see [v4 migration guide](https://github.com/webpack/webpack-dev-server/blob/master/migration-v4.md) and [v5 migration guide](https://github.com/webpack/webpack-dev-server/blob/master/migration-v5.md). Some common issues are:
+    - **contentBase** and **watchContentBase** were removed; use **static**
+    - **disableHostCheck** was removed; use `allowedHosts: 'all'`
+    - **hotOnly** was removed; use `hot: 'only'`
+    - **http2** and **https** were removed; use **server**
+    - **injectClient** and **injectHot** were removed in favor of manual setup entries
+    - **inline** was removed without replacement
+    - **proxy** only accepts an array
+    - **publicPath**, **stats** and **writeToDisk** were moved to **devMiddleware**
 
 ## v25.0.0
 
 ### [@servicetitan/ajax-handlers](./ajax-handlers)
 
--   Changed [**withMicroservice**](./ajax-handlers#parameters) arguments to a single options object.
+- Changed [**withMicroservice**](./ajax-handlers#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,
+- 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;`)
+    - 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;`)
 
     See [this blogpost](https://devblogs.microsoft.com/typescript/announcing-typescript-5-0/) for the complete list of changes.
 
@@ -74,15 +80,15 @@ title: BREAKING CHANGES
 
 ### [@servicetitan/eslint-config](./eslint-config)
 
--   Upgraded **@typescript-eslint/eslint-plugin** from version v5.x to v6. Because every new major version includes improvements and changes to existing rules, expect to see new lint errors in your project.
+- Upgraded **@typescript-eslint/eslint-plugin** from version v5.x to v6. Because every new major version includes improvements and changes to existing rules, expect to see new lint errors in your project.
 
 ### [@servicetitan/react-ioc](./react-ioc/)
 
--   Changed second argument of **provide** method to an object with **loadingFallback** and **errorFallback** properties.
--   Renamed the **fallback** property of the **Provider** component to **loadingFallback** and added **errorFallback** property.
--   Removed ability to use **useValue** with **instances**.
+- Changed second argument of **provide** method to an object with **loadingFallback** and **errorFallback** properties.
+- Renamed the **fallback** property of the **Provider** component to **loadingFallback** and added **errorFallback** property.
+- Removed ability to use **useValue** with **instances**.
 
 ### [@servicetitan/startup](./startup)
 
--   Upgraded **Jest** from version v27 to v29. The largest breaking change is that v29 changed the default snapshot format.<br/>
-    To update old snapshots, run `npm run test -- --updateSnapshot`. See [Upgrading from v27 to v28](https://jest-archive-august-2023.netlify.app/docs/28.x/upgrading-to-jest28) and [Upgrading from v28 to v29](https://jestjs.io/docs/upgrading-to-jest29) for detailed lists of all breaking changes.
+- Upgraded **Jest** from version v27 to v29. The largest breaking change is that v29 changed the default snapshot format.<br/>
+  To update old snapshots, run `npm run test -- --updateSnapshot`. See [Upgrading from v27 to v28](https://jest-archive-august-2023.netlify.app/docs/28.x/upgrading-to-jest28) and [Upgrading from v28 to v29](https://jestjs.io/docs/upgrading-to-jest29) for detailed lists of all breaking changes.

package/docs/launchdarkly-service.mdx

@@ -140,6 +140,30 @@ export const HostApp: FC = () => {
 };
 ```
 
+### LDService
+
+The `LDService` interface enables [headless bundles](./web-components/headless-loader#headlesscallback) to create and reuse client connections for LaunchDarkly projects.
+
+```ts
+export interface LDService {
+    getClient: (config: ClientConfig) => LDClient;
+}
+
+export interface ClientConfig {
+    clientSideID: string;
+    context?: LDContext;
+}
+```
+
+#### getClient
+
+Returns an `LDClient` instance configured with the following parameters.
+
+| Name           | Type     | Description                                                         |
+| :------------- | :------- | :------------------------------------------------------------------ |
+| `clientSideID` | `string` | The LaunchDarkly client-side ID.                                    |
+| `context`      | `object` | (Optional) Context for targeting rules. Defaults to anonymous user. |
+
 ### FeatureFlagStore
 
 `LDProvider` automatically provides a `FeatureFlagStore` that allows you to access

package/docs/startup/build.mdx

@@ -0,0 +1,28 @@
+---
+title: build
+---
+
+Build packages for production to the `dist/bundle` folders. It bundles them in production mode and optimizes the build for the best performance. The builds are minified and the filenames include the hashes. Apps are ready to be deployed.
+
+#### Arguments
+
+- `--scope <glob>` - Include only packages with names matching the given glob.
+- `--ignore <glob>` - Exclude packages with names matching the given glob.
+- `--cdn-path <url>` - Specify the base path for all the assets within the application.
+- `--stat` - Generate bundle report with [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer). Starting `v22.3.0` works for [MFEs](/docs/frontend/micro-frontends) too.
+- `--code-coverage` - Add [instrumentation](https://github.com/JS-DevTools/coverage-istanbul-loader) to bundled code in order to collect code coverage
+- `--use-tsc` - Use TSC for TypeScript compilation
+
+## Build Steps
+
+The `build` command executes these steps:
+
+1. Activate Kendo UI license.
+1. Compile Typescript.
+1. Generate TypeScript definitions from CSS, LESS, and SASS modules, and copy assets and style files to the output folder.
+1. Run type check via [TypeScript project references](https://www.typescriptlang.org/docs/handbook/project-references.html).
+1. Bundle application and MFE packages.
+
+:::note
+`startup` doesn't support dependencies between the Webpack bundles.
+:::

package/docs/startup/clean.mdx

@@ -0,0 +1,13 @@
+---
+title: clean
+---
+
+Resets project workspace to a fresh state by clearing build caches and removing untracked files.
+
+It runs tools like `nx reset` and `jest --clearCache` to clear project and test
+caches, and then uses `git clean -fdX` to delete all untracked files and
+directories (such as build outputs and temporary files).
+
+```sh
+npx --yes @servicetitan/startup clean
+```

package/docs/startup/convert-eslint-config.mdx

@@ -0,0 +1,18 @@
+---
+title: convert-eslint-config
+---
+
+Convert an ESLint v8 configuration to v9 format.
+
+```sh
+npx startup convert-eslint-config
+```
+
+Use this command when upgrading from ESLint v8 to v9, to convert a v8 `.eslintrc.json` to the equivalent `eslint.config.mjs`. See [Upgrading to ESLint v9.x](/docs/frontend/upgrading-to-eslint-v9) for guidance on upgrading to ESLint v9.
+
+The command takes no arguments. Simply run it from a directory with `.eslintrc.json` and it creates `eslint.config.mjs` in the same location.
+
+:::caution
+Comments are not copied from the source `.eslintrc.json` to the output file.
+If the source file contains important comments, copy them manually to the output file.
+:::

package/docs/startup/init.mdx

@@ -0,0 +1,9 @@
+---
+title: init
+---
+
+Generates initial project structure. This command should be run via `npx` in an empty folder.
+
+```sh
+npx -y @servicetitan/startup@latest init
+```

package/docs/startup/install.mdx

@@ -0,0 +1,13 @@
+---
+title: install
+---
+
+Installs project dependencies.
+
+Use this command instead of plain `npm install` to guarantee that all packages are installed correctly and any necessary post-install steps are performed.
+
+```sh
+npx --yes @servicetitan/startup install
+```
+
+See [package.json in the example project](https://github.com/search?q=repo%3Aservicetitan%2Ffrontend-example+path%3A**%2Fpackage.json+%22startup+install%22&type=code) for how to use `install` in an npm script.

package/docs/startup/kendo-ui-license.mdx

@@ -0,0 +1,20 @@
+---
+title: kendo-ui-license
+---
+
+Activates KendoReact components by installing the license key. The license key is only installed if the project depends on `@progress/kendo` components. Otherwise, this command has no effect.
+
+**Note:** The [build](#build) command automatically detects when a project uses KendoRect components and runs this command.
+
+Use it to install the license key separately from a build, or to override the default license key.
+
+```sh
+npx startup kendo-ui-license
+```
+
+To install a different license, set the KENDO_UI_LICENSE environment variable to the key to use.
+
+```sh
+export KENDO_UI_LICENSE=<license-key>
+npx startup kendo-ui-license
+```

package/docs/startup/lint.mdx

@@ -0,0 +1,24 @@
+---
+title: lint
+---
+
+Runs ESLint and Stylelint for all codebase projects.
+
+To run ESLint and Stylelint on certain packages or subsystems it is possible to pass paths to specific directories as positional parameters.
+
+```sh
+npx startup lint -- packages/desktop/app/modules/inventory/
+```
+
+You can use multiple paths and your shell expressions which expand to directories.
+
+```sh
+npx startup lint -- packages/desktop/app/modules/lead/ packages/desktop/app/modules/inventory/
+npx startup lint -- packages/desktop/app/modules/{lead,inventory}/
+```
+
+#### Options
+
+- `--scope <glob>` - Include only packages with names matching the given glob.
+- `--ignore <glob>` - Exclude packages with names matching the given glob.
+- `--fix` - Fix linting issues.

package/docs/startup/mfe-publish.mdx

@@ -0,0 +1,45 @@
+---
+title: mfe-publish
+---
+
+This is an umbrella command for both publishing and unpublishing (cleaning up) MFEs. This command allows publishing MFEs in a way that there is no risk of colliding package versions (a common issue with back-merging). See the `--build` option for more details.
+
+#### Publishing options
+
+| Option              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--build <glob>`    | Optional build version that normally should not be specified. Defaults to `<branch_name>.<commit_hash>`. For example, if git commit `bdac90f5` is published from branch `next`, the build version is`next.bdac90f5`, and the full version is `0.0.0-next.bdac90f5`. This ensures each release has a unique version with no collisions.                                                                                                                                                                                                                                                                                           |
+| `--dry`             | Invoke [npm publish --dry-run](https://docs.npmjs.com/cli/v7/commands/npm-publish#dry-run) instead of actually publishing anything.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `--branch <string>` | Optional branch name. The current branch name is used if no value is specified. The branch name is used in constructing the build version in case `--build` is not specified.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `--force`           | Forces publishing the package when no configuration was found for the specified branch (`--branch` or current branch).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `--tag <string>`    | The [tag](https://docs.npmjs.com/cli/v7/commands/npm-publish#tag) to assign to the published version. Defaults to the tag associated with the branch from the custom [branch config](#branch-configs) or, if there is no custom branch config, from the [default branch config](https://github.com/servicetitan/uikit/blob/master/packages/startup/src/utils/get-branch-configs.ts#L3). For example, by default a package published from the `master` branch is tagged `prod`. Becasue NPM v11 requires pre-release versions to have a tag, if there is no custom or default tag for the branch, the package is tagged "latest". |
+
+#### Unpublishing options
+
+| Option             | Descripiton                                                                                                                                   |
+| :----------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--clean`          | Instructs `mfe-publish` to remove old versions instead of publishing.                                                                         |
+| `--count <number>` | The number of package versions to keep (e.g., if twelve versions are published, `--count 10` removes the two oldest). The default value is 5. |
+| `--branch <name>`  | Remove old versions associated with the specified branch. Defaults to the current branch (i.e., `git branch --show-current`)                  |
+| `--all`            | Remove old versions associated with all [recognized branches](#branch-configs). This overrides `--branch`.                                    |
+| `--dry`            | Log what the command would do without actually unpublishing anything.                                                                         |
+
+#### Branch configs
+
+By default `mfe-publish` only publishes from a few [recognized branches](https://github.com/servicetitan/uikit/blob/master/packages/startup/src/utils/get-branch-configs.ts#L3) and you must use `--force` to publish from others.
+
+To customize the recognized branches for an MFE set `cli.web-component.branches` in the MFE's package.json to an object that maps branch names to the associated tag. For example,
+
+```json
+    "cli": {
+        "web-component": {
+            "branches": {
+                "qa": { "publishTag": "qa" },
+                "staging": { "publishTag": "staging" },
+                "master": { "publishTag": "prod" }
+            }
+        }
+    }
+```
+
+- `publishTag: string` - Tag used when publishing package.