Skip to content

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
· 95 commits to main since this release
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