Repository navigation
Releases
v0.6.1 — clear every Dependabot alert
Security housekeeping only — nothing user-facing changed. dist/ in this release is byte-identical to 0.6.0 for every package; only the version stamp and CHANGELOG.md differ. If you're consuming openTagCloud from npm, there is nothing here to gain by upgrading. This release exists so the repo builds and tests clean against a tree with no known advisories.
Every advisory below lived in the development tree. None of it was reachable from a published bundle, so no consumer was ever exposed.
The last open alert: vitest
GHSA-82fw-gwwq-j7x9 — path traversal / arbitrary file read via a @vitest/mocker redirect mock. @vitest/mocker registered a redirect target without checking it against the dev server's file-serving allowlist, so anything that could reach the Vite HMR socket could point a mock outside the project root and read the file back as module source.
Dependabot filed this seven times — once per workspace declaring vitest, plus two against the lockfile — but it was a single advisory with a single fix: 4.1.11, a major over the ^3.0.0 pinned in core, svelte, react, vue, and solid.
The major turned out to need no migration. All five vitest.config.ts files are jsdom plus a setup file, and nothing in that surface moved in v4. Verified before merging: 73 vitest tests, 10 Angular jest tests, 23 Playwright e2e tests, plus build, check, and lint — all green.
Two criticals that npm audit fix could not reach
next carried two unauthenticated-RCE advisories (GHSA-p293-qw3h-jr36, GHSA-2xp9-vwfh-vxw4) and neither npm audit fix nor npm update next would move it. The reason is worth recording: next reached the tree only as a peer dependency, and npm will not raise a peer on its own — so the lockfile sat on 16.3.0 no matter what was run against it.
The fix was to add next as a real devDependency at ^16.3.4. The peer range deliberately stays at >=13.0.0. Narrowing it would push every consumer onto a newer Next.js to resolve a vulnerability in this repo's own CI install, which is not their problem to absorb. The devDependency pins what we build and test against; the peer keeps stating what's actually supported.
Also cleared: fast-uri, browserslist, js-yaml, baseline-browser-mapping, and sharp.
npm audit now reports 0 vulnerabilities, and Dependabot has no open alerts.
Verifying the "no runtime change" claim
Rather than asserting it, the new build was packed and diffed against the published 0.6.0 tarball:
diff -rq old/package new/package | grep -v 'CHANGELOG.md|package.json'
(nothing)
Identical dist/ for both @opentagcloud/core and opentagcloud.
Full changelog: v0.6.0...v0.6.1
v0.6.0 — fillFactor for negative space, and density that actually packs
Two layout controls that now work together instead of cancelling each other out.
Published entirely through npm trusted publishing, so every artifact carries
SLSA provenance.
🆕 fillFactor — negative space in sized containers
In a container with a fixed height the packer scales the font ramp up until the
cloud fills the box. fillFactor (0–1) says how much of the box to claim:
| Value | Behaviour |
|---|---|
1 |
Fills the container with the largest type that fits — the 0.5.x behaviour. |
0.75 |
The new default. Fills most of it, leaving some air. |
0 |
No growth at all: type stays at the minPx/maxPx ramp you authored. |
<div style="height: 320px">
<TagCloud {items} fillFactor={0.5} />
</div>Available on all six renderers, on mount()/renderTagCloud() (plus
setFillFactor()), and as a fill-factor attribute on <otc-tag-cloud>. It has
no effect on auto-height containers, which already pack to their natural area,
and it is unrelated to fill ('width' | 'height' | 'both'), which spreads
terms to cover the height.
Treat it as a target rather than an exact ratio — the type is grown in discrete
steps with a retry if the result overflows, so two nearby values can land on the
same step. The trend across the range is what is meaningful.
🔧 density now controls spacing, not just anchors
density was supposed to make terms cluster, but measuring the shipped 0.5.0
behaviour showed it barely changed the rendered cloud — 0–5% in most
configurations. Anchor contraction alone gets masked: with many terms they need
the full width regardless, and the elliptical growth front spreads a tight
cluster sideways.
It now scales the gap between terms as well, which is the other half of
"packed as close to each other". Raising it visibly compacts the cloud: ink
inside the cloud's own bounding box rises from roughly 0.23 to 0.35, and the
cloud gets shorter. 0.5 keeps the historical 5px gap, so that default is
unchanged.
✨ Why these shipped together
The two settings were fighting: at full fill, growing the type absorbed exactly
the space that tighter packing freed up, so density had nothing to show. With
room to spare they compose — fillFactor decides how much of the box the
words claim, density how tightly they sit within it.
The live examples now
demonstrate each in isolation: the density cards hold type at one size so
clustering is the only variable, and the new fill-factor cards show coverage
dropping from 0.34 to 0.13 of the box.
⚠️ Upgrade notes
Both defaults are visible changes to existing clouds:
- Type is slightly smaller in fixed-height containers than in 0.5.x, because
fillFactordefaults to 0.75 rather than filling completely. Pass
fillFactor={1}to restore the previous look exactly. - Terms sit at the same default spacing as before (
density0.5 → 5px), but any
non-defaultdensitynow affects gaps as well as placement.
Install
npm install opentagcloud # Svelte 5 + vanilla mount() + <otc-tag-cloud>
npm install @opentagcloud/react # or /vue, /angular, /solid, /next, /coreFull changelog: v0.5.0...v0.6.0
v0.5.0 — security fixes for untrusted tag data, clickable tags, container-shaped clouds
Two security fixes for untrusted tag data, clickable tags, and layout controls. All seven packages are at 0.5.0 with SLSA provenance.
🔒 Security
Tag data is frequently user-generated, and two TagCloudItem fields reached the DOM unvalidated.
hrefaccepted any scheme and was assigned straight to the anchor, sojavascript:alert(1)was click-to-XSS in the vanilla renderer and the Svelte, Vue and Solid adapters (React blocks it; Angular sanitizes). Only relative URLs and safe schemes (http,https,mailto,tel,ftp,sms) now become links; anything else renders as text. Whitespace and control characters spliced into a scheme are stripped before it's read, since browsers ignore them.colorwas interpolated into a style string, so a;closed the custom property and appended declarations —red;background-image:url(//evil.test/p.png)made the browser fetch an attacker URL. Colors are now restricted to the characters CSS colors need; hex,rgb()/hsl()/oklch()/color-mix()andvar()all still work.
Both are validated in one place, so every renderer inherits them. class and id remain trusted input — SECURITY.md documents the full boundary, and private vulnerability reporting is now enabled.
✨ Added
onTagClickon every adapter (tagClickoutput in Angular, an option onmount()/renderTagCloud()). Non-link tags render as<button type="button">— focusable, keyboard-operable, correctly announced — with no visual change. Links still fire it, sopreventDefault()can take over routing. Nothing becomes focusable without a handler.density(0–1, default0.5):0distributes terms evenly across the container,1packs them tightly around the centre leaving the corners empty. Terms never overlap at any setting.SECURITY.mdandCONTRIBUTING.md.
🔄 Changed
- Clouds take their container's aspect ratio. Each term's growth front is stretched to the box, so a wide container gets a wide elliptical cloud instead of a circle floating in the middle. On a 3.6:1 container the cloud's aspect went from ~1.25 to ~3.5.
- The default arrangement is slightly clustered (
densitydefaults to0.5). - Tooltips no longer default to the raw weight — "95" means nothing to a visitor.
item.titlestill sets one;ariaLabelgives the explained form.
🐛 Fixed
- Duplicate labels crashed the Svelte adapter. Two tags sharing a
labelwith noidthreweach_key_duplicateand took down the component. Keys are now de-duplicated (Java,Java#2, …). mount()exposessetFill(), matchingrenderTagCloud(), and<otc-tag-cloud>adjustsfillin place rather than remounting (which discarded the packed layout and its animation).- Published packages now contain the MIT
LICENSE— every package declared it, none shipped it.CHANGELOG.mdships too.
⬆️ Upgrading
Layouts will look different: clouds are shaped to their container and slightly clustered by default. density={0} restores the previous even spread, though the elliptical shaping stays. Unsafe href/color values are dropped rather than rendered, and tooltips no longer show a weight number.
npm install opentagcloud # Svelte 5 + vanilla mount() + <otc-tag-cloud>
npm install @opentagcloud/react # or /vue, /angular, /solid, /next, /coreFull changelog: v0.4.2...v0.5.0
v0.4.2 — all Dependabot alerts cleared, provenance-signed unattended releases
All seven packages are published at 0.4.2, and this is the first release
where every artifact carries SLSA provenance —
built and published by GitHub Actions with no credential in the loop.
🔒 Security: all 24 Dependabot alerts cleared
npm audit now reports 0 vulnerabilities at any severity, and all
Dependabot alerts on the repository are closed as fixed. Every alert was
reached through package-lock.json; none of them were in shipped code paths.
Transitive, no declared range touched — npm audit fix resolved these:
next 16.2.10 → 16.3.0 (9 alerts), postcss → 8.5.26 (4), sharp
0.34.5 → 0.35.3, plus js-yaml, fast-uri, nanoid and brace-expansion.
Angular needed a major bump. All five Angular advisories were scoped
<= 19.2.25 with no patched version declared — 19.2.25 is the last 19.x
release, so the fixes exist only in later majors and staying on 19 meant
staying vulnerable. The Angular adapter's devDependencies moved to
Angular 20.3, the smallest bump that clears them (pulling TypeScript
5.7 → 5.8, since compiler-cli peers >=5.8 <6.0, and jest-preset-angular
14.5 → 14.6, the last line supporting Angular 20 on jest 29).
Consumers are unaffected.
@opentagcloud/angularstill declares
peerDependencies: { "@angular/core": ">=17.0.0" }— Angular is only this
repo's build and test toolchain, not something the package imposes on you.
A subtlety worth recording: the root overrides block is load-bearing, not
decoration. npm fills a root peer slot for the adapter's >=17.0.0
independently of its devDependencies and had chosen 19.2.25 — leaving the
flagged version at the tree root while the workspace itself used 20.3.27
nested below. Dependabot scans the root, so without that pin the alerts would
have survived an otherwise-successful upgrade.
SvelteKit removed, which retired the last advisory. The final three alerts
were a single advisory (cookie < 0.7.0) reached only via @sveltejs/kit,
whose current release still depends on cookie ^0.6.0 — there was no version
to upgrade to. It turned out nothing used SvelteKit: no source file imported
@sveltejs/kit, $app/* or $env/*. The published package is built by
svelte-package from src/lib, the Pages site by scripts/build-pages.mjs,
and the Playwright suite serves its own fixtures. SvelteKit existed solely to
serve a one-page demo, which is now a plain Vite app — so a framework with a
server, router, SSR and prerendering left the tree along with the advisory.
🚀 Releases are now unattended, with provenance
Publishing used to mean relaying a dozen short-lived npm 2FA links. A release
is now a tag push:
git tag v0.4.3 && git push origin v0.4.3.github/workflows/release.yml runs the full verify pipeline (lint → build →
svelte-check → unit tests → Playwright) and publishes all seven packages in
dependency order, authenticating via npm trusted publishing (OIDC) — no
token stored anywhere, and provenance attestations
are generated automatically. Requires npm ≥ 11.5.1, so the workflow runs
Node 24 (Node 22 still bundles npm 10.9.x).
📖 Docs
The README's Releasing section was rewritten to cover trusted publishing, token
auth, and local publishing.
Looking for the font-legibility fix, the framework-first examples site, or the
npm installinstructions? Those shipped in
v0.4.1.
Install
npm install opentagcloud # Svelte 5 + vanilla mount() + <otc-tag-cloud>
npm install @opentagcloud/react # or /vue, /angular, /solid, /next, /coreFull changelog: v0.4.1...v0.4.2
v0.4.1 — fix: fit scaling no longer shrinks type below legible sizes
A patch release fixing a font-legibility regression in 0.4.0's new
fit-to-container layout, plus documentation and examples work.
🔤 Fixed: fit scaling could shrink type to illegible sizes
0.4.0 taught the packer to fit an externally sized container by scaling the
whole font ramp. It scaled in both directions, though — down to ×0.5 — so a
dense cloud in a small box was crammed at unreadable sizes instead of
overflowing at normal ones, a regression from 0.4.0's predecessors.
Fit scaling is now grow-only, clamped to ×1–×2.5:
- a container with room still gets maximized type, which was the point of the
feature - a container too small for the tags at their base sizes now overflows
it — legibility wins over fit, matching pre-0.4.0 behavior - overflow retries floor at ×1 and stop early once they reach it
minPx/maxPx therefore act as the relative ramp and a genuine floor, not
merely a starting point. Pinned by a regression test: 80 tags in a 600×250 box,
asserting zero tags render below their base ramp size and that the cloud
overflows rather than crams.
📖 Docs & examples
- README install instructions — a per-package
npm installcommand for all
seven packages, plus the CDN script-tag alternative, and each framework quick
start now leads with its own install line. - Live examples site leads with the
frameworks — the "One engine, every framework" cloud is now the first card
(with a matching nav chip), and each framework tag links straight to its npm
package. - The Sizing section documents the grow-only fit behavior.
Install
npm install opentagcloud # Svelte 5 + vanilla mount() + <otc-tag-cloud>
npm install @opentagcloud/react # or /vue, /angular, /solid, /next, /coreFull changelog: v0.4.0...v0.4.1
v0.4.0 — framework-agnostic monorepo: core + Svelte, React, Vue, Angular, Solid, Next
The release that took openTagCloud from a Svelte 5 component to a
framework-agnostic tag cloud with seven packages — and the first version
published to npm as a monorepo.
Upgrading from 0.2.x/0.3.x? The Svelte component keeps its package name
(opentagcloud) and its API. Two things moved — see the⚠️ Breaking
changes section at the end.
📦 One engine, seven packages
All layout logic lives in @opentagcloud/core — zero dependencies, plain
TypeScript. Every adapter is a thin (~60–100 line) wrapper that renders tags in
its own framework's template syntax, so SSR and hydration stay native, then
hands the container to the shared engine.
| Package | Use with |
|---|---|
@opentagcloud/core |
Vanilla JS, script tag, <otc-tag-cloud>, custom adapters |
opentagcloud |
Svelte 5 / SvelteKit (name unchanged) |
@opentagcloud/react |
React 18+ — ships 'use client', works in Next.js |
@opentagcloud/vue |
Vue 3 / Nuxt |
@opentagcloud/angular |
Angular 17+ — standalone component |
@opentagcloud/solid |
SolidJS / SolidStart |
@opentagcloud/next |
Next.js (alias of the React adapter) |
The core splits cleanly in two: prepareTags() is pure and DOM-free (safe
during SSR, and the reason every adapter produces identical markup), while
TagCloudLayout is the packer, driven entirely by data-fs / data-weight /
data-key attributes — it doesn't care which framework rendered the elements.
🚫 No build step required
@opentagcloud/core also ships a browser global that registers a light-DOM
<otc-tag-cloud> custom element, so a cloud can be one tag on any page:
<script src="https://unpkg.com/opentagcloud/dist/opentagcloud.vanilla.js"></script>
<otc-tag-cloud style="height: 320px" min-px="14" max-px="44"
items='[{"label":"JavaScript","weight":95},{"label":"Rust","weight":60}]'>
</otc-tag-cloud>Items work as a JSON attribute or an items property; mount() and
defineElement() are also importable from opentagcloud/vanilla.
✨ Layout features
- Fit to container — with an externally imposed height, the packer scales
the font ramp to fill the box instead of packing to natural area. Auto-height
containers keep area-based packing, so layout can never feed back on itself.
(Scaled both ways here; 0.4.1
makes it grow-only.) - Movement animations — re-packs FLIP smoothly from old positions, new tags
scale in, via--otc-move-transition. Honorsprefers-reduced-motion; the
initial pack never animates. - Incremental stability (opt-in
incremental) — unchanged tags keep their
positions across item updates, so live-updating clouds stay calm. - RTL support — tags position with
inset-inline-start, so the whole layout
mirrors underdir="rtl". estimateCloudHeight()— pure, DOM-free height estimate for reserving
min-heightduring SSR to reduce layout shift.- Accessibility —
ariaLabelannounces each tag's weight to screen readers,
minOpacitylets themes hold WCAG AA contrast, and transitions respect
reduced-motion. - Performance — collision detection via a spatial hash and incremental
farthest-point anchor ordering; a 400-tag re-pack runs in ~15 ms. - Text fidelity — labels are never rewritten. Hyphenated words render inside
white-space: nowrapspans, so copy/paste, find-in-page and screen readers
see the real string.
✅ Tests
61 unit tests and 18 Playwright end-to-end tests, all in CI: core unit tests
(including golden RNG values that guard SSR/hydration scatter parity), render
tests for all five framework adapters, and browser tests asserting no
overlaps, deterministic layout, the loop-safety invariant, RTL mirroring, fit
mode, and the UMD/custom-element path.
🌐 Live examples
hkoren.github.io/openTagCloud —
interactive examples plus standalone pages for the vanilla/custom-element,
RTL, and Svelte demos, deployed from main.
⚠️ Breaking changes
- CSS class names are now
.otc-tag/.otc-cloud(they must be global,
unscoped classes). Custom styling that targeted.tag/.cloudneeds
updating. dist/is no longer committed, sonpm install github:hkoren/openTagCloud
is replaced by the npm packages above.- The Svelte component's own props and behavior are unchanged.
Install
npm install opentagcloud # Svelte 5 + vanilla mount() + <otc-tag-cloud>
npm install @opentagcloud/react # or /vue, /angular, /solid, /next, /core