@deviceinsight/ng-ui-components 7.22.0 → 7.24.0

package/README.md

@@ -1,18 +1,109 @@
+# General
+
+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`.
+
+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:
+
+```ts
+import '@deviceinsight/ng-ui-components/style.css';
+```
+
+`react`, `react-dom`, `i18next`, `react-i18next` and `react-router-dom` are peer
+dependencies and have to be provided by the consuming project.
+
+## Contents
+
+`src/index.ts` is the public API. It currently exports:
+
+- **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`, …)
+
+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.
+
+# Development
+
+Node is pinned via `.nvmrc` (see also the `engines` field in `package.json`).
+
+```shell
+npm install
+npm run storybook   # dev server on http://localhost:6006
+```
+
+Available scripts:
+
+| 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`                |
+
+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`).
+
+Commits are checked by a husky `pre-commit` hook that runs `lint-staged`
+(prettier on the staged files).
+
+`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>`.
+
 # Linking for local development
 
-We recommend using `yalc` tool for linking `ng-ui-components`. It's because `yalc` generates exactly the same package as
+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 `yarn link`.
+problems when we use `npm link`.
 
 Here's how to do the linking:
 
 ```shell
-yarn link-local
+npm run build
+npx yalc publish
 
 # in the project where you want to link this library to:
-yalc link "@deviceinsight/ng-ui-components"
+npx yalc link "@deviceinsight/ng-ui-components"
 ```
 
+# CI
+
+`.gitlab-ci.yml` installs the dependencies and then runs `test`, `scan`, `lint` and
+`typecheck` on every branch except `main`. 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`.
+
 # Releasing the library using git flow
 
 ## Prerequisites
@@ -24,7 +115,8 @@ The git flow tools need to be installed. This depends on your operating system.
 They can be also installed from the git repo: https://github.com/petervanderdoes/gitflow-avh
 
 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).
+question with the default (press Enter/Return). The script verifies that the branches
+are named `main` and `develop`.
 
 ## Building a release
 
@@ -34,9 +126,8 @@ To build a release of this library, execute `./release.sh`, which consists of th
 
 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:
+in the release process will not fail, the script runs the checks locally before building the
+release:
 
 ```
 npm install
@@ -44,12 +135,16 @@ npm run scan
 npm run test
 ```
 
+If `package-lock.json` changed during the install, the script commits it.
+
 ### Building the release
 
 1. Switch to develop branch and make sure both main and develop are current:
 
 `git checkout develop && git pull && git fetch origin main:main`
 
+The script also aborts if the workarea is dirty or if `develop` has unpushed commits.
+
 2. Get the upcoming release from `package.json` and start the release:
 
 `git flow release start $RELEASE_VERSION`, e.g. `git flow release start 1.2.0`.
@@ -86,7 +181,7 @@ so that the version is e.g. `1.2.0-SNAPSHOT`.
 
 5.2. Run `npm install`.
 
-5.2. Commit `package.json` and `package-lock.json`. Commit message should be `Starting $NEW_SNAPSHOT_VERSION`, e.g. `Starting 1.2.0`.
+5.3. Commit `package.json` and `package-lock.json`. Commit message should be `Starting $NEW_SNAPSHOT_VERSION`, e.g. `Starting 1.2.0`.
 
 6. Push the branches and the tag: