@opentagcloud/core 0.3.0

package/README.md

@@ -0,0 +1,78 @@
+# @opentagcloud/core
+
+Framework-agnostic core of [openTagCloud](https://github.com/hkoren/openTagCloud)
+— a dependency-free, self-packing, SSR-friendly tag cloud. This package is the
+layout engine plus a vanilla-JS renderer; framework adapters
+(`opentagcloud` for Svelte, `@opentagcloud/react`, `@opentagcloud/vue`,
+`@opentagcloud/angular`, `@opentagcloud/solid`, `@opentagcloud/next`) are thin
+wrappers over it.
+
+## Vanilla usage
+
+```js
+import { renderTagCloud } from '@opentagcloud/core';
+
+const cloud = renderTagCloud(document.querySelector('#cloud'), [
+  { label: 'JavaScript', weight: 95, href: '/tags/javascript' },
+  { label: 'TypeScript', weight: 88 },
+  { label: 'Rust', weight: 60, color: 'tomato' },
+]);
+
+cloud.update(newItems); // replace items and re-pack
+cloud.destroy(); // stop observing, remove tags
+```
+
+Give the container a sized parent; the cloud packs to its width and grows its
+`min-height` to fit. Styles are injected at runtime — no CSS setup needed. For
+server-rendered pages, also ship `@opentagcloud/core/styles.css` so the no-JS
+fallback (justified inline flow) is styled before hydration.
+
+## Script tag / custom element (no build step)
+
+The package also ships a browser global (`dist/opentagcloud.vanilla.js`, the
+`unpkg`/`jsdelivr` entry) that registers a light-DOM `<otc-tag-cloud>` custom
+element and exposes `openTagCloud.mount(container, items, options)`:
+
+```html
+<script src="https://unpkg.com/@opentagcloud/core/dist/opentagcloud.vanilla.js"></script>
+
+<otc-tag-cloud
+  style="height: 320px"
+  items='[{ "label": "Rust", "weight": 60 }]'
+>
+</otc-tag-cloud>
+```
+
+`mount()` and `defineElement()` are also exported from the package root and the
+`./vanilla` subpath for ES-module consumers (call `defineElement()` to register
+the element). Both are thin wrappers over `renderTagCloud` — same engine, same
+markup contract. Try the
+[live vanilla example](https://hkoren.github.io/openTagCloud/) or view the
+[`example source`](examples/vanilla.html).
+
+## SSR height estimation
+
+`estimateCloudHeight(items, width, options?)` is pure and DOM-free: emit it as
+the container's `min-height` during SSR to reserve space and avoid layout
+shift (roughly ±25% of the real packed height).
+
+## Building your own adapter
+
+- `prepareTags(items, { minPx, maxPx })` — pure and DOM-free: returns each
+  tag's font size, opacity, key, display text, and inline style. Call it in
+  your template layer (works during SSR).
+- Render one element per prepared tag with its `className`, `style`, `title`,
+  and `data-fs` / `data-weight` / `data-key` attributes, inside a container
+  with class `otc-cloud`. Render its `parts` as the content — `nowrap` parts go
+  in a `<span class="otc-nb">` so lines never break at a hyphen while the DOM
+  text stays byte-identical to the label.
+- `new TagCloudLayout(container, { fill }).attach()` on mount; `refresh()`
+  after the tags change; `destroy()` on teardown. All methods are no-ops
+  without a DOM.
+
+See the [project README](https://github.com/hkoren/openTagCloud#readme) for
+props, theming, and how the packer works.
+
+## License
+
+MIT © Henry Koren

package/dist/estimate.d.ts

@@ -0,0 +1,19 @@
+import type { TagCloudItem } from './types.js';
+import { type PrepareOptions } from './prepare.js';
+/**
+ * Estimate the packed height of a cloud for a given container width — without
+ * a DOM, so it can run during SSR. Emit it as the container's `min-height` to
+ * reserve space before hydration and avoid layout shift (CLS):
+ *
+ * ```svelte
+ * <div style="min-height: {estimateCloudHeight(items, 720)}px">
+ *   <TagCloud {items} />
+ * </div>
+ * ```
+ *
+ * It mirrors the packer's own area-based box-height formula, with text
+ * measured by a character-width heuristic instead of the real font metrics,
+ * so expect roughly ±25% — enough to absorb the fallback→packed reflow. A
+ * fixed-height container is still the zero-shift option.
+ */
+export declare function estimateCloudHeight(items: TagCloudItem[], width: number, options?: PrepareOptions): number;

package/dist/estimate.js

@@ -0,0 +1,48 @@
+import { prepareTags } from './prepare.js';
+import { PAD, LOOSEN, widthFactor } from './layout.js';
+/**
+ * Estimate the packed height of a cloud for a given container width — without
+ * a DOM, so it can run during SSR. Emit it as the container's `min-height` to
+ * reserve space before hydration and avoid layout shift (CLS):
+ *
+ * ```svelte
+ * <div style="min-height: {estimateCloudHeight(items, 720)}px">
+ *   <TagCloud {items} />
+ * </div>
+ * ```
+ *
+ * It mirrors the packer's own area-based box-height formula, with text
+ * measured by a character-width heuristic instead of the real font metrics,
+ * so expect roughly ±25% — enough to absorb the fallback→packed reflow. A
+ * fixed-height container is still the zero-shift option.
+ */
+export function estimateCloudHeight(items, width, options = {}) {
+    if (!items.length || width < 2)
+        return 0;
+    const wf = widthFactor(width);
+    const wide = width >= 380;
+    // average advance width of a bold system-font glyph, in em
+    const GLYPH = 0.58;
+    let area = 0;
+    let tallest = 0;
+    for (const p of prepareTags(items, options)) {
+        const fs = Math.max(8, p.fontPx * wf);
+        const textW = p.text.length * fs * GLYPH;
+        let w;
+        let lines = 1;
+        if (wide) {
+            // nowrap; the packer shrinks anything wider than the container
+            w = Math.min(textW, width);
+        }
+        else {
+            const maxW = Math.min(6.5 * fs, width);
+            lines = Math.max(1, Math.ceil(textW / maxW));
+            w = Math.min(textW, maxW);
+        }
+        const h = lines * fs * 0.95; // line-height 0.95
+        area += (w + PAD) * (h + PAD);
+        tallest = Math.max(tallest, h);
+    }
+    return Math.ceil(Math.max((area * LOOSEN) / width, tallest));
+}
+//# sourceMappingURL=estimate.js.map

package/dist/estimate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"estimate.js","sourceRoot":"","sources":["../src/estimate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAuB,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEvD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAqB,EACrB,KAAa,EACb,UAA0B,EAAE;IAE5B,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC;IACzC,MAAM,EAAE,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAC9B,MAAM,IAAI,GAAG,KAAK,IAAI,GAAG,CAAC;IAC1B,2DAA2D;IAC3D,MAAM,KAAK,GAAG,IAAI,CAAC;IACnB,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,MAAM,CAAC,IAAI,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,CAAC;QAC5C,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;QACtC,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,KAAK,CAAC;QACzC,IAAI,CAAS,CAAC;QACd,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,IAAI,IAAI,EAAE,CAAC;YACT,+DAA+D;YAC/D,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAC7B,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,EAAE,EAAE,KAAK,CAAC,CAAC;YACvC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC;YAC7C,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAC5B,CAAC;QACD,MAAM,CAAC,GAAG,KAAK,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,mBAAmB;QAChD,IAAI,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;QAC9B,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,MAAM,CAAC,GAAG,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;AAC/D,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export type { TagCloudItem, Fill } from './types.js';
+export { prepareTags, keyOf } from './prepare.js';
+export type { PreparedTag, PrepareOptions, LabelPart } from './prepare.js';
+export { TagCloudLayout } from './layout.js';
+export type { TagCloudLayoutOptions } from './layout.js';
+export { renderTagCloud, createTagElement } from './render.js';
+export type { RenderOptions, TagCloudHandle } from './render.js';
+export { injectStyles, TAG_CLOUD_CSS } from './styles.js';
+export { makeRng } from './rng.js';
+export { mount, defineElement } from './vanilla.js';
+export type { MountOptions, CloudHandle } from './vanilla.js';
+export { estimateCloudHeight } from './estimate.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+export { prepareTags, keyOf } from './prepare.js';
+export { TagCloudLayout } from './layout.js';
+export { renderTagCloud, createTagElement } from './render.js';
+export { injectStyles, TAG_CLOUD_CSS } from './styles.js';
+export { makeRng } from './rng.js';
+export { mount, defineElement } from './vanilla.js';
+export { estimateCloudHeight } from './estimate.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/D,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAEpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC"}

package/dist/layout.d.ts

@@ -0,0 +1,59 @@
+import type { Fill } from './types.js';
+export interface TagCloudLayoutOptions {
+    /** Also spread terms vertically to fill the container's height. */
+    fill?: Fill;
+    /**
+     * Add the component stylesheet to the document on `attach()` (default true).
+     * Set false if you serve `@opentagcloud/core/styles.css` yourself.
+     */
+    injectStyles?: boolean;
+    /**
+     * Keep unchanged tags in place when `refresh()` runs after an item update:
+     * tags whose measured box still fits at its old position stay put; only
+     * new, resized, or displaced tags are re-placed (seeded from their old
+     * position, so they move minimally). Falls back to a full re-pack when the
+     * width changed or more than 40% of tags would move. Off by default — a
+     * full re-pack always produces the canonical deterministic layout.
+     */
+    incremental?: boolean;
+}
+/** @internal Gap between tag boxes; shared with estimateCloudHeight(). */
+export declare const PAD = 5;
+/** @internal Area slack factor used to derive the packing box height. */
+export declare const LOOSEN = 1.4;
+/** @internal container width → font: shrink on narrow (mobile), grow modestly when wide. */
+export declare const widthFactor: (w: number) => number;
+/**
+ * The self-packing layout engine. Framework-free: it operates on a container
+ * element whose children carry class `otc-tag` plus three data attributes —
+ * `data-fs` (base font px), `data-weight`, and `data-key` (scatter seed) — all
+ * emitted by `prepareTags()`. How those elements got into the DOM (a framework
+ * template, `renderTagCloud()`, or server-rendered HTML) is irrelevant.
+ *
+ * Lifecycle: construct with the container, call `attach()` once it's in the
+ * document, `refresh()` after the tag elements change, `destroy()` on teardown.
+ * All methods are no-ops without a DOM, so adapters can call them under SSR.
+ *
+ * Re-packs and re-distributions animate: moved tags FLIP from their previous
+ * visual position, new tags scale in. Duration/easing come from the
+ * `--otc-move-transition` custom property (default `250ms` ease-out); set it
+ * to `0s` or `none` to disable, and `prefers-reduced-motion: reduce` disables
+ * it automatically. The initial pack never animates.
+ */
+export declare class TagCloudLayout {
+    #private;
+    constructor(root: HTMLElement, options?: TagCloudLayoutOptions);
+    /** Start observing the container and pack the initial layout. */
+    attach(): void;
+    /** Re-pack after the tag elements changed (items added/removed/re-weighted). */
+    refresh(): void;
+    /** Change the fill mode; only term positions move, never the container height. */
+    setFill(fill: Fill | undefined): void;
+    /** Stop observing. The current positions are left in place. */
+    destroy(): void;
+    pack(): void;
+    distribute(flipFrom?: Map<string, {
+        x: number;
+        y: number;
+    }> | null): void;
+}