@deviceinsight/ng-ui-components 7.21.0 → 7.22.1

package/README.md

@@ -1,99 +1,173 @@
-# Linking for local development
-
-We recommend using `yalc` tool for linking `ng-ui-components`. It's because `yalc` generates exactly the same package as
-it would be published to the npm registry, especially it removes files that should be ignored and their existence cause
-problems when we use `yarn link`.
+# General
 
-Here's how to do the linking:
+This project contains the higher-level React components shared by
+[NG-UI](https://gitlab.device-insight.com/ng-ui/ng-ui) and custom projects.
+It is published as `@deviceinsight/ng-ui-components` and builds on
+`@deviceinsight/ng-ui-basic-components` and `@deviceinsight/ng-ui-api-client`.
 
-```shell
-yarn link-local
+The package is ESM-first (`dist/index.js`) with a CommonJS build (`dist/index.cjs`)
+and type declarations (`dist/types/index.d.ts`). The bundled stylesheet is exported
+separately and has to be imported by the consuming project:
 
-# in the project where you want to link this library to:
-yalc link "@deviceinsight/ng-ui-components"
+```ts
+import '@deviceinsight/ng-ui-components/style.css';
 ```
 
-# Releasing the library using git flow
-
-## Prerequisites
-
-### git flow
-
-The git flow tools need to be installed. This depends on your operating system.
+`react`, `react-dom`, `i18next`, `react-i18next` and `react-router-dom` are peer
+dependencies and have to be provided by the consuming project.
 
-They can be also installed from the git repo: https://github.com/petervanderdoes/gitflow-avh
+## Contents
 
-After git flow is installed, the repo needs to be initialized. Run `git flow init` and answer every
-question with the default (press Enter/Return).
+`src/index.ts` is the public API. It currently exports:
 
-## Building a release
+- **Inputs** — `DateInput`, `DateTimeInput`, `UrnInput`, `ValidatedTextInput`,
+  `SelectWithSearch`, `SelectWithSearchAsync`, `PeriodPicker`, `Slider`
+- **Data display** — `Reactable`, `ReactableWithClientSidePagination`, `Pagination`,
+  `TreeView` (plus `getTreeNodePathById`), `Chart`, `InfoBox`, `ContentHeader`
+- **Color pickers** — `ColorPicker` / `GridColorPicker`, `GradientColorPicker`
+- **Navigation** — `RouteLink`, `RouteTabs`, `MultiMenu`, `MultiMenuItem`
+- **Upload** — `FileUpload`, `ImageUpload`
+- **SVG** — `SvgImage` and the helpers `getSvgElement`, `getMutableNodeList`,
+  `validateSvg`
+- **Prompt** — `withPrompt`
+- **Message box** — `messageBoxSuccess`, `messageBoxInfo`, `messageBoxWarn`,
+  `messageBoxError`, `messageBoxDismissSingle`, `messageBoxDismissGroup`,
+  `messageBoxDismissAll`, `setGlobalMessageBoxOptions`,
+  `setGlobalErrorMessageBoxOptions`, `MessageBoxContainer`
+- **Utilities** — `uuidV4`, `nanoid10`, `initializeTranslation`
+- the accompanying types (`ReactableProps`, `ReactableColumnDef`, `Period`,
+  `SvgImageProps`, `PaginationSettings`, …)
 
-To build a release of this library, execute `./release.sh`, which consists of the following steps:
+Translations live in `src/i18n` and are set up by calling `initializeTranslation`.
+`src/modules` holds non-component code (message box, utils), `src/styles` the
+stylesheet, `src/utils` shared helpers.
 
-### Before the release: Check for vulnerabilities and run the tests
+# Development
 
-Vulnerabilities can occur at any time.
-To be sure, the pipeline for the branches and the tags created
-in the release process will not fail, it is wise to run the checks locally before building the
-release.
-To do this, run:
+Node is pinned via `.nvmrc` (see also the `engines` field in `package.json`).
 
-```
+```shell
 npm install
-npm run scan
-npm run test
+npm run storybook   # dev server on http://localhost:6006
 ```
 
-### Building the release
-
-1. Switch to develop branch and make sure both main and develop are current:
+Available scripts:
 
-`git checkout develop && git pull && git fetch origin main:main`
+| Script                    | Description                                                                |
+| ------------------------- | -------------------------------------------------------------------------- |
+| `npm run build`           | Cleans `dist`, bundles with Vite and emits types via `tsconfig.types.json` |
+| `npm test`                | Runs the Vitest suite (watch mode by default, `--run` for a single pass)   |
+| `npm run watch`           | Rebuilds and runs `yalc push` on every successful compile                  |
+| `npm run clean`           | Removes `dist`                                                             |
+| `npm run storybook`       | Starts Storybook on port 6006                                              |
+| `npm run build-storybook` | Builds the static Storybook                                                |
+| `npm run typecheck`       | `tsc --noEmit`                                                             |
+| `npm run lint`            | Lints with oxlint and checks formatting with Prettier                      |
+| `npm run prettier`        | Formats the sources and `.mdx` files                                       |
+| `npm run scan`            | Vulnerability scan via `audit-ci` using `scan-config.json5`                |
 
-2. Get the upcoming release from `package.json` and start the release:
+Tests use Vitest with `happy-dom` and Testing Library; the setup lives in
+`vitest.setup.tsx` and the config in `vitest.config.mts`. Components are additionally
+exercised via Storybook stories (`*.stories.tsx`).
 
-`git flow release start $RELEASE_VERSION`, e.g. `git flow release start 1.2.0`.
+Commits are checked by a husky `pre-commit` hook that runs `lint-staged`
+(prettier on the staged files).
 
-3. Edit the version in `package.json`.
+`CHANGELOG.md` is maintained per version. Renovate dependency updates append their
+entry automatically via the `postUpgradeTasks` hook in `renovate.json`, which calls
+`./update-changelog.sh <depName> <currentVersion> <newVersion>`.
 
-3.1. Edit the version in `package.json`, remove the `-SNAPSHOT`.
+# Linking for local development
 
-3.2. Commit `package.json`. Commit message should be `Release $RELEASE_VERSION`, e.g. `Release 1.2.0`.
+We recommend using the `yalc` tool for linking `@deviceinsight/ng-ui-components`. It's because `yalc` generates exactly the same package as
+it would be published to the npm registry, especially it removes files that should be ignored and their existence cause
+problems when we use `npm link`.
 
-4. Finish the release:
+Here's how to do the linking:
 
-`git flow release finish`
+```shell
+npm run build
+npx yalc publish
 
-This will merge the release branch into the `main` branch and create a tag.
-It will also merge the release branch into the `develop` branch.
+# in the project where you want to link this library to:
+npx yalc link "@deviceinsight/ng-ui-components"
+```
 
-After this you should be on the `develop` branch.
+# CI
 
-4.1 A merge conflict might occur in `package.json` for the `version`, when main is merged into the develop branch:
+`.gitlab-ci.yml` installs the dependencies and then runs `test`, `lint` and `typecheck`
+on every branch except `main`. The `audit` job (`npm run scan`) only runs on `develop`,
+`feature/*` and `renovate/*` branches, so hotfixes and tags are not blocked by it. On `develop` the
+`pages` job publishes the static Storybook to GitLab Pages. The `publish` job runs for `develop` and for tags:
+`-SNAPSHOT` versions are published to the internal Nexus registry under the `next`
+tag, releases go to the public npm registry. A release older than the currently
+published `latest` is published under a `hotfix-<major>.<minor>` tag so that `latest`
+is not moved backwards. `publish_alpha` is a manual job that publishes an alpha
+prerelease of the `VERSION` variable to the internal registry under `next`.
 
-Resolve it by taking the version of the `develop` branch. Then run `npm install` to resolve conflicts in `package-lock.version`.
+# Releasing the library using git flow
 
-Run `git status` to see if there are more conflicts. If there are, resolve them and `git add` the fixed files.
+## Prerequisites
 
-If there are no more conflicts, run `git add package*` and `git commit`.
+### git flow
 
-5. Start a new snapshot version:
+The git flow tools need to be installed. This depends on your operating system.
 
-5.1.
-Edit the version in `package.json`,
-increment the minor version (e.g., from `1.1.0` to `1.2.0`) and add the `-SNAPSHOT` again,
-so that the version is e.g. `1.2.0-SNAPSHOT`.
+They can be also installed from the git repo: https://github.com/petervanderdoes/gitflow-avh
 
-5.2. Run `npm install`.
+After git flow is installed, the repo needs to be initialized. Run `git flow init` and answer every
+question with the default (press Enter/Return). The script verifies that the branches
+are named `main` and `develop`.
 
-5.2. Commit `package.json` and `package-lock.json`. Commit message should be `Starting $NEW_SNAPSHOT_VERSION`, e.g. `Starting 1.2.0`.
+## Releasing the develop branch
 
-6. Push the branches and the tag:
+Run the release script from the repository root:
 
-On branch `develop`:
+```shell
+./release.sh
+```
 
-`git push`
-`git checkout main`
-`git push`
-`git push --tags`
-`git checkout develop`
+Before running it, make sure the workarea is clean and all commits on `develop` are pushed; otherwise the script aborts.
+It releases the current version from `package.json` (without `-SNAPSHOT`) and afterwards starts the next minor snapshot version.
+
+## Building a hotfix for a specific version of this library
+
+When building a hotfix in `ng-ui-scale`, first check which version of this library is used on the `main` branch of `ng-ui-scale`, e.g. with `git show origin/main:package.json | grep ng-ui-components`.
+Then build the hotfix on top of exactly that version, so that no unrelated changes from newer releases end up in the `ng-ui-scale` hotfix.
+Do not use `release.sh` or `git flow hotfix` for this: `git flow hotfix finish` merges into `main`, which already contains the newer release.
+
+Example: `ng-ui-scale` uses 7.22.0 while 7.24.0 is already released (the version on `main` of this library):
+
+1. Create the branch `hotfix/7.22.1` from the tag 7.22.0:
+   ```shell
+   git fetch --tags
+   git checkout -b hotfix/7.22.1 7.22.0
+   ```
+2. Set the version in `package.json` and `package-lock.json` to 7.22.1:
+   ```shell
+   npm version 7.22.1 --no-git-tag-version
+   ```
+   If the `audit` job in `.gitlab-ci.yml` still runs on every branch except `main`, copy its `rules` from `develop`, so that the vulnerability audit does not block the hotfix pipeline.
+3. Implement or cherry-pick the changes needed for the hotfix, either directly on the hotfix branch or in a feature branch that is merged into it.
+4. Add a `## Version 7.22.1` entry to `CHANGELOG.md` describing the changes in the hotfix.
+5. Run `npm run build`, `npm test -- --run` and `npm run lint` to verify there are no errors.
+6. Commit the changes.
+7. Tag the hotfix commit and push the tag:
+   ```shell
+   git tag -a 7.22.1 -m "Hotfix 7.22.1"
+   git push origin 7.22.1
+   ```
+   The `publish` CI job builds the tag and publishes it to npm.
+   Because 7.22.1 is older than the `latest` version, it is published under the dist-tag `hotfix-7.22` and `latest` stays at 7.24.0.
+8. Merge the hotfix branch into `develop` and push `develop`:
+   ```shell
+   git checkout develop
+   git pull
+   git merge --no-ff hotfix/7.22.1
+   git push
+   ```
+   `package.json` and `package-lock.json` will conflict; keep the `-SNAPSHOT` version of `develop` and run `npm install` before committing the merge.
+   In `CHANGELOG.md`, keep the 7.22.1 entry between the entries for 7.23.0 and 7.22.0.
+   Do not merge the hotfix branch into `main`.
+9. Delete the local hotfix branch: `git branch -d hotfix/7.22.1`.
+10. Update `ng-ui-scale` on its hotfix branch to 7.22.1.

package/dist/index.cjs

@@ -6,7 +6,6 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 var __copyProps = (to, from, except, desc) => {
 	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
 		key = keys[i];
@@ -73,7 +72,6 @@ let _svgdotjs_svg_js = require("@svgdotjs/svg.js");
 let highcharts = require("highcharts");
 highcharts = __toESM(highcharts, 1);
 let highcharts_react_official = require("highcharts-react-official");
-highcharts_react_official = __toESM(highcharts_react_official, 1);
 let _rc_component_slider = require("@rc-component/slider");
 _rc_component_slider = __toESM(_rc_component_slider, 1);
 let _rc_component_tooltip = require("@rc-component/tooltip");
@@ -3326,9 +3324,10 @@ var getClickConfiguration = (onClick) => {
 var Chart = class extends react.Component {
 	constructor(..._args) {
 		super(..._args);
-		this.state = {};
+		this.state = { titleApplied: false };
 		this.chart = null;
 		this.ro = null;
+		this.titleTimeoutId = void 0;
 		this.handleChart = (chart) => {
 			this.chart = chart;
 			this.ro = new ResizeObserver(() => {
@@ -3338,8 +3337,16 @@ var Chart = class extends react.Component {
 		};
 	}
 	componentDidMount() {
+		this.titleTimeoutId = setTimeout(() => this.setState({ titleApplied: true }), 0);
+	}
+	/**
+	* Builds the Highcharts configuration from the props. Everything here is derived, so it is
+	* rebuilt while rendering rather than mirrored into state.
+	*/
+	buildOptions() {
 		const { type, title, items, tooltipTitle, valueFormatter, onClick } = this.props;
-		this.setState({
+		const { titleApplied } = this.state;
+		return {
 			...initialOptions,
 			plotOptions: {
 				...initialOptions.plotOptions,
@@ -3356,44 +3363,12 @@ var Chart = class extends react.Component {
 				...initialOptions.legend,
 				enabled: type === "pie"
 			},
-			yAxis: {
-				...initialOptions.yAxis,
-				enabled: type === "column",
-				title: { text: title || "" }
-			},
-			series: [{
-				type,
-				innerSize: "50%",
-				data: items.map(({ label, value }) => [label, value])
-			}]
-		});
-		setTimeout(() => {
-			this.setState({ title: {
-				...initialOptions.title,
-				text: type === "column" ? "" : title || ""
-			} });
-		}, 0);
-	}
-	componentDidUpdate(prevProps) {
-		const { type, title, items, tooltipTitle, valueFormatter, onClick } = this.props;
-		if (title !== prevProps.title) this.setState({
 			title: {
-				...this.state.title,
-				text: type === "column" ? "" : title || ""
-			},
-			yAxis: {
-				...this.state.yAxis,
-				title: { text: title || "" }
-			}
-		});
-		if (type !== prevProps.type) this.setState({
-			legend: {
-				...this.state.legend,
-				enabled: type === "pie"
+				...initialOptions.title,
+				text: titleApplied && type !== "column" ? title || "" : ""
 			},
-			title: { text: type === "column" ? "" : title || "" },
 			yAxis: {
-				...this.state.yAxis,
+				...initialOptions.yAxis,
 				enabled: type === "column",
 				title: { text: type === "column" ? title || "" : "" }
 			},
@@ -3402,35 +3377,19 @@ var Chart = class extends react.Component {
 				innerSize: "50%",
 				data: items.map(({ label, value }) => [label, value])
 			}]
-		});
-		if (!(0, lodash.isEqual)(items, prevProps.items)) this.setState({ series: [{
-			type,
-			innerSize: "50%",
-			data: items.map(({ label, value }) => [label, value])
-		}] });
-		if (tooltipTitle !== prevProps.tooltipTitle || valueFormatter !== prevProps.valueFormatter || onClick !== prevProps.onClick) this.setState({
-			tooltip: {
-				...initialOptions.tooltip,
-				formatter() {
-					const format = valueFormatter || ((value) => value);
-					return createTooltip(tooltipTitle || "", this.point.name, format(this.point.y));
-				}
-			},
-			plotOptions: {
-				...initialOptions.plotOptions,
-				...getClickConfiguration(onClick)
-			}
-		});
+		};
 	}
 	componentWillUnmount() {
+		clearTimeout(this.titleTimeoutId);
 		if (this.ro && this.chart?.renderTo) this.ro.unobserve(this.chart.renderTo);
 		this.chart = null;
 		this.ro = null;
 	}
 	render() {
-		return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(highcharts_react_official.default, {
+		const built = this.buildOptions();
+		return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(highcharts_react_official.HighchartsReact, {
 			highcharts: highcharts.default,
-			options: this.props.updateOptions ? this.props.updateOptions(this.state) : this.state,
+			options: this.props.updateOptions ? this.props.updateOptions(built) : built,
 			containerProps: { className: this.props.className },
 			callback: this.handleChart
 		});
@@ -3438,54 +3397,15 @@ var Chart = class extends react.Component {
 };
 //#endregion
 //#region src/components/slider/RcSliderWithTooltip.tsx
-var import_raf = /* @__PURE__ */ __toESM((/* @__PURE__ */ __commonJSMin(((exports) => {
-	Object.defineProperty(exports, "__esModule", { value: true });
-	exports.default = void 0;
-	var raf = (callback) => +setTimeout(callback, 16);
-	var caf = (num) => clearTimeout(num);
-	if (typeof window !== "undefined" && "requestAnimationFrame" in window) {
-		raf = (callback) => window.requestAnimationFrame(callback);
-		caf = (handle) => window.cancelAnimationFrame(handle);
-	}
-	var rafUUID = 0;
-	var rafIds = /* @__PURE__ */ new Map();
-	function cleanup(id) {
-		rafIds.delete(id);
-	}
-	var wrapperRaf = (callback, times = 1) => {
-		rafUUID += 1;
-		const id = rafUUID;
-		function callRef(leftTimes) {
-			if (leftTimes === 0) {
-				cleanup(id);
-				callback();
-			} else {
-				const realId = raf(() => {
-					callRef(leftTimes - 1);
-				});
-				rafIds.set(id, realId);
-			}
-		}
-		callRef(times);
-		return id;
-	};
-	wrapperRaf.cancel = (id) => {
-		const realId = rafIds.get(id);
-		cleanup(id);
-		return caf(realId);
-	};
-	if (process.env.NODE_ENV !== "production") wrapperRaf.ids = () => rafIds;
-	exports.default = wrapperRaf;
-})))(), 1);
 var HandleTooltip = (props) => {
 	const { value, children, visible, tipFormatter = (val) => `${val}`, ...restProps } = props;
 	const tooltipRef = (0, react.useRef)(null);
 	const rafRef = (0, react.useRef)(null);
 	function cancelKeepAlign() {
-		if (rafRef.current) import_raf.default.cancel(rafRef.current);
+		if (rafRef.current) cancelAnimationFrame(rafRef.current);
 	}
 	function keepAlign() {
-		rafRef.current = (0, import_raf.default)(() => {
+		rafRef.current = requestAnimationFrame(() => {
 			tooltipRef.current?.forceAlign();
 		});
 	}