Skip to content

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