visivalab-components

Vue 3 component library with Leaflet (VMap) and MapLibre maps.

Development

Use Node.js 22 and the committed npm lockfile:

npm ci
npm run storybook

The project .npmrc enables legacy-peer-deps for its existing dependency tree. npm ci also applies the Leaflet patches in patches/; keep installation scripts enabled. The patches are included in the compiled library, so the npm package ships the dist/ output rather than patches to apply to a consumer's dependencies.

Tests and builds

npm test                  # VMap regression tests, one run
npm run test:watch        # Interactive development
npm run test:coverage     # Coverage report and minimum thresholds
npm run test:release      # Release version and publishing safeguards
npm run release:prepare   # Increment patch version in manifest and lockfile
npm run check:release     # Manifest/lockfile consistency
npm run build-lib
npm run build-storybook
npm run check:package     # Pack, inspect and install in a temporary consumer

The VMap tests use a controlled Leaflet implementation in jsdom to exercise Vue lifecycle, props, map events and layer interactions. Integration tests also mount the real Leaflet, compass, Geoman and rotation plugins, render SVG geometry and dispatch DOM clicks. Turf geometry tests use the real library. Tests do not fetch tile servers or verify rendering in a real browser. VMap requires at least 90% line, statement and function coverage and 80% branch coverage. Reports are written to coverage/, Storybook to storybook-static/, and the tested npm tarball to .artifacts/. Package checks install the tarball with lifecycle scripts enabled and validate its entry points, stylesheet and JavaScript syntax.

VMap updates and performance

VMap still observes nested changes to polygon descriptors, pins and tile settings. Polygon updates retain the 300 ms throttle, and pin updates retain the 2000 ms debounce. Props, emitted events, callback payloads, polygon ordering and zoom thresholds are unchanged.

Unchanged polygon layers and their parsed/simplified geometries are reused. Snapshots detect in-place edits, at the cost of keeping a copy of each active descriptor. Stable polygon uuid values help preserve identity across descriptor replacements; UUIDs remain optional. Pins update position and icon in place, and switching base layers reuses the existing tile groups.

Click tests reject points outside cached geometry bounds before calling Turf. Turf still decides polygon boundaries, holes and overlaps, including explicit turfPolygon overrides. The shortcut is bypassed while a throttled in-place update is pending. Regression tests verify layer reuse, deep mutations, drawing order, hover cleanup and click behavior with both controlled and real Leaflet.

GitHub Actions

Pull requests targeting master, pushes to master, and manual CI runs invoke the same validation workflow. It installs from the lockfile, tests VMap and release safeguards, enforces coverage thresholds, builds the library and Storybook, and checks an actual consumer installation. Coverage, library, Storybook and npm package artifacts are retained for 14 days. Storybook is built and downloadable; the workflow does not deploy it to a website.

dist/ is currently tracked in Git. CI rebuilds it from source before packing; releases always publish that tested tarball. CI does not commit generated output.

One-time publishing setup

1. Enable Actions for Visivalab/visivalab-components and allow the pinned official GitHub actions used in .github/workflows/.
2. Create a GitHub environment named npm. Restrict deployment tags to v* and configure any approval policy required by the team. The workflow also requires the tagged commit to belong to master.
3. In the npm settings for visivalab-components, add a GitHub Actions trusted publisher: organization Visivalab, repository visivalab-components, workflow release.yml, environment npm, allowed action Publish.
4. After the first CI run, make Test, build and package a required branch protection/ruleset check for master if your repository plan supports it.

Publication uses OIDC and requires no NPM_TOKEN. Only the publishing job receives id-token: write; it downloads the tested tarball without installing project dependencies or running package lifecycle scripts. It uses Node 22 and an npm 11 version with trusted publishing support. The repository is private, so npm does not generate provenance attestations. See the official npm trusted publishing documentation.

Release a version

Every release must include a version increment in both package.json and package-lock.json. Prepare it on a branch from master, then commit both files and push them through the usual review process. The default increment is patch:

npm run release:prepare

Use npm run release:prepare -- minor or -- major for larger changes. The command updates and validates the manifest and both lockfile root versions. For prereleases, use npm version prerelease --preid=rc --no-git-tag-version and npm run check:release.

After the version commit is merged and CI passes, tag that commit with the exact package version and push the tag. For example, if package.json is 0.2.236:

git tag v0.2.236
git push origin v0.2.236

The Release workflow reruns all validation, checks the tag against both manifest and lockfile, verifies that its commit is on master, publishes the tested tarball to npm, then creates a GitHub release with that same tarball. Before installation and builds, it rejects versions already published to npm and stable versions that do not advance npm's latest version. A registry error stops validation so publishing cannot continue with an unverified version. Stable versions use npm's latest tag; prereleases such as 0.3.0-rc.1 use next and create a GitHub prerelease. Build metadata (+...) is not accepted. An existing npm version cannot be overwritten; always increment the version.

If only the GitHub release job fails after npm publication, use Re-run failed jobs to retry that job without publishing the package again.