Skip to content

Releases

v0.6.1 — clear every Dependabot alert

Choose a tag to compare

@hkoren hkoren released this 10 Sep 02:23
4e4f30d

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

Choose a tag to compare

@hkoren hkoren released this 12 Aug 04:06
5938e8d

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
    fillFactor defaults 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 (density 0.5 → 5px), but any
    non-default density now 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, /core

Full changelog: v0.5.0...v0.6.0

v0.5.0 — security fixes for untrusted tag data, clickable tags, container-shaped clouds

Choose a tag to compare

@hkoren hkoren released this 10 Aug 00:51
db027fa

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.

  • href accepted any scheme and was assigned straight to the anchor, so javascript: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.
  • color was 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() and var() 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

  • onTagClick on every adapter (tagClick output in Angular, an option on mount()/renderTagCloud()). Non-link tags render as <button type="button"> — focusable, keyboard-operable, correctly announced — with no visual change. Links still fire it, so preventDefault() can take over routing. Nothing becomes focusable without a handler.
  • density (0–1, default 0.5): 0 distributes terms evenly across the container, 1 packs them tightly around the centre leaving the corners empty. Terms never overlap at any setting.
  • SECURITY.md and CONTRIBUTING.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 (density defaults to 0.5).
  • Tooltips no longer default to the raw weight — "95" means nothing to a visitor. item.title still sets one; ariaLabel gives the explained form.

🐛 Fixed

  • Duplicate labels crashed the Svelte adapter. Two tags sharing a label with no id threw each_key_duplicate and took down the component. Keys are now de-duplicated (Java, Java#2, …).
  • mount() exposes setFill(), matching renderTagCloud(), and <otc-tag-cloud> adjusts fill in 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.md ships 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, /core

Full changelog: v0.4.2...v0.5.0

v0.4.2 — all Dependabot alerts cleared, provenance-signed unattended releases

Choose a tag to compare

@hkoren hkoren released this 08 Aug 14:46
5567d49

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/angular still 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 install instructions? 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, /core

Full changelog: v0.4.1...v0.4.2

v0.4.1 — fix: fit scaling no longer shrinks type below legible sizes

Choose a tag to compare

@hkoren hkoren released this 08 Aug 20:53
ab03706

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 install command 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, /core

Full changelog: v0.4.0...v0.4.1

v0.4.0 — framework-agnostic monorepo: core + Svelte, React, Vue, Angular, Solid, Next

Choose a tag to compare

@hkoren hkoren released this 08 Aug 20:53
5b51855

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. Honors prefers-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 under dir="rtl".
  • estimateCloudHeight() — pure, DOM-free height estimate for reserving
    min-height during SSR to reduce layout shift.
  • Accessibility — ariaLabel announces each tag's weight to screen readers,
    minOpacity lets 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: nowrap spans, 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 / .cloud needs
    updating.
  • dist/ is no longer committed, so npm 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