app: "pp-components" app_type: "tooling" lifecycle: "active" keywords: ["react", "components", "design-system", "pp-dev"]

@metricinsights/pp-components

Overview

A collection of reusable React components for building Metric Insights Portal Page applications: announcement, breadcrumbs, drawer, element card, info popup, modal, preloader, search, select, sidebar, slider, tabs and tag.

Each component lives in its own repository and is pulled in here as a git submodule, one directory per component under src/components/ (the list is in component-list.json). This repository bundles them into one npm package, so every Portal Page built on pp-dev shares the same components instead of reimplementing them. Package usage for consumers is in NPM-README.md, which is published as the package README.

Deployment

The package is published to npm as @metricinsights/pp-components by the shared mi-examples-workflows release flow. The settings are in .github/mi-examples-workflows.json. The callers in .github/workflows/ are generated from it, so don't edit them by hand.

| When | What happens | | -- | -- | | Pull request into develop or main | CI: lint, typecheck, tests, build, the dist and package-contents checks, npm audit and a secret scan. | | Push to develop | Publishes X.Y.Z-beta.N under the beta dist-tag, if there are feat/fix/perf commits since the last release. | | Actions → Release → Run workflow | Opens the release pull request into main, with the version bump and the CHANGELOG entry. | | Merging the release pull request | Publishes X.Y.Z under latest, tags it, creates the GitHub release, then opens the back-merge into develop. |

• Builds. Every build checks out the submodules at the commits pinned in this repository, using the DEPLOY_KEY secret.
• Publishing. It uses npm Trusted Publishing (OIDC) from the npm-publish environment. No npm token is involved.
• Package README. NPM-README.md becomes the package's README.md during npm pack/npm publish (the prepack/postpack scripts).

Requirements

• Node.js 24 for development (@metricinsights/pp-dev 1.x needs it). The package itself declares node >= 22.
• SSH access to the mi-pp component repositories, for the submodules.

Getting started

git clone --recurse-submodules [email protected]:mi-pp/pp-components.git
cd pp-components
npm ci
npm run dev

In an existing clone, fetch the submodules with npm run dev:submodule:init. It checks out the commits pinned in this repository.

npm run dev starts the pp-dev playground (src/app.tsx) at http://localhost:3000/pl/@metricinsights/pp-components. It runs standalone, without an MI backend. To proxy a real instance, set mi.url in pp-dev.config.ts:

import { defineConfig } from '@metricinsights/pp-dev';

export default defineConfig({
  mi: {
    url: 'https://example.metricinsights.com',
    mode: 'standalone',
  },
  app: {
    type: 'page',
  },
});

See the pp-dev documentation for all options.

Demo page

npm run build:demo builds the playground as a Portal Page that shows every component. The build goes to dist-demo/ and the zip to dist-zip/pp-components-demo.zip; dist/ stays the library build. To put it on an MI instance, upload the zip to a Portal Page there. Alternatively, set mi.url, app.id and app.type: 'template' in pp-dev.config.ts and let pp-dev sync it (it needs MI_ACCESS_TOKEN).

Scripts

| Script | What it does | | -- | -- | | npm run dev | Starts the playground with pp-dev. | | npm run build | Builds dist/esm, dist/cjs and dist/types with Rollup. | | npm run build:demo | Builds the playground as a Portal Page into dist-demo/ and dist-zip/ (see Demo page). | | npm run lint | ESLint (flat config in eslint.config.js) over this repository and the published component sources, with --max-warnings 0. | | npm run typecheck | tsc --noEmit over the component sources (tsconfig.json), the playground (tsconfig.app.json) and the tests (tsconfig.test.json). | | npm test | Runs the component tests once with Vitest. npm run test:watch reruns them on changes. | | npm run dev:submodule:init | Checks out all submodules at their pinned commits. | | npm run dev:submodule:update | Moves every submodule to its remote main. Commit the new pointers on purpose, in their own pull request. | | npm run components | Compares component-list.json with the submodules. components:sync adds missing ones, components:remove removes extra ones. | | npm run components-add -- <name> <git-url> | Adds a component submodule and records it in component-list.json. |

Adding a component

New and changed components follow COMPONENTS.md: prop naming, the component shape, styles and CSS variables, accessibility, tests and the README format. Its last section lists the renames planned for 1.0.

1. Create the component repository with its code under src/components/<name>/ and an index.ts that exports it. Copy the dev setup from an existing component repository (for example tag-component): the demo app, package.json scripts, eslint.config.js, the tsconfigs and .github/.
2. Add it here: npm run components-add -- <name> [email protected]:mi-pp/<repo>.git.
3. Export it from src/components/index.ts: export * from './<name>/src/components/<name>';
4. Add tests/<name>.test.tsx (see Tests).
5. Run npm run lint, npm test and npm run build, and check the new entries in dist/.

The build picks up every .ts/.tsx file under src/components/*/src/components/*/. Each component is also available as @metricinsights/pp-components/<name>.

Changing a component

Changes to a component go to its own repository first. Every component repository has a demo page (npm run dev) and CI (lint, typecheck, build) on the same tooling as this repository; see the "Development" section of its README. Tests live here. After the change is merged there, update the submodule pointer here in a separate commit:

git -C src/components/<name> fetch origin
git -C src/components/<name> checkout origin/main
git add src/components/<name>

Tests

The tests live in tests/ and import the components from src/components, so one run covers the code pinned in every submodule. They run with Vitest in jsdom, with Testing Library and axe-core.

• What each component has. A render test, a test of its main interaction, and an axe check (axeViolations in tests/axe.ts; color contrast is off, because jsdom has no layout).
• Known bugs. A bug that isn't fixed yet goes in a describe('known bugs (PP-XXXX)') block, as it.fails. Such a test passes while the bug is there, and fails once a fix lands in the component. Change it.fails to it in the pull request that bumps the submodule.
• No layout. jsdom doesn't measure or scroll. tests/setup.ts stubs ResizeObserver and Element.scrollTo. tests/slider.test.tsx shows how to mock sizes where a component measures them.
• Class names. CSS modules keep their source class names in tests (slider-item, open), so a test can query an element that has no role.

Contributing

• Branch from develop and open pull requests into develop.
• Use Conventional Commits with the Linear issue as the scope, e.g. fix(PP-1234): keep the sidebar folder closed. The release tooling derives versions from them: feat releases a minor, fix/perf a patch, and docs, chore, ci, build, refactor nothing.
• CI (npm run lint, typecheck, test and build) must pass.