=== Clouddy ===
Contributors: jaclas
Tags: tag cloud, tags, post_tag, taxonomy
Requires at least: 6.3
Tested up to: 7.0
Requires PHP: 8.0
Stable tag: 0.5.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Visual tag cloud, sized and colored by popularity, with many ordering modes. Add as a block, shortcode, or widget — fully stylable with CSS.

== Description ==

Clouddy renders a visual tag cloud (`post_tag` or any other taxonomy) with dynamic sizing
and a smooth color transition based on tag popularity. Configuration is global; embed the
cloud with a block, a widget, or a shortcode.

Sizing and color are computed in PHP only as a normalized weight; the actual font size and
color are produced in CSS (custom properties + `calc()` + `color-mix()`), so you can override
everything with plain CSS — no `!important` needed.

Features:

* Selection modes: most popular, rarest, random, and hybrid (some popular + some rare).
* Display orders independent of selection: by count, alphabetical, random, and "lens" orders
  (longest / most popular / rarest in the center).
* Exclusion blocklist, configurable taxonomy, adjustable size range and colors.
* Server-side cache (Transients) with invalidation on content and term changes.
* Clean, override-friendly HTML; accessible navigation container with an aria-label.

== Installation ==

1. Upload the `clouddy` folder to `/wp-content/plugins/`, or install the plugin through the
   WordPress "Plugins" screen.
2. Activate the plugin through the "Plugins" screen in WordPress.
3. Go to Settings → Clouddy to configure the cloud (the configuration is global).
4. Place the cloud with the `[clouddy]` shortcode, the Clouddy block, or the widget.
5. To customize a single cloud, pass attributes to the shortcode (e.g. `[clouddy mode="hybrid" number="40"]`) — see the FAQ for the full list of supported attributes.

== Frequently Asked Questions ==

= How do I change the tag sizes? =

In Settings → Clouddy set the minimum and maximum text size and the unit (rem/em/px). Each
tag's size is interpolated between those values based on the tag's popularity.

= Can I style the cloud with my own CSS? =

Yes. The default stylesheet only sets custom properties on the container; every value can be
overridden with regular CSS, and the default stylesheet can be dequeued entirely.

= How do I embed the tag cloud? =

Three ways, all rendering the same cloud from the global settings (Settings → Clouddy):

* Block — add the "Clouddy — Tag Cloud" block in the block editor.
* Shortcode — `[clouddy]` (accepts attributes, see below).
* Widget — the "Clouddy — Tag Cloud" classic widget (themes with widget areas).

= Which shortcode attributes are supported? =

Every attribute is optional and overrides the global setting for that single cloud, e.g. `[clouddy mode="hybrid" number="40" order="name_asc"]`:

* `mode` — which tags to include: `popular`, `rare`, `random`, `hybrid`. Default `popular`.
* `number` — total number of tags (integer, min 1). Default `30`.
* `order` — display order: `count_desc`, `count_asc`, `name_asc`, `name_desc`, `random`, `length_center`, `count_center`, `rare_center`. Default `count_desc`. The `*_center` orders place the top-ranked tags in the middle (lens effect).
* `rare_count` — hybrid mode only: how many of the total are the rarest (integer, capped at `number`). Default `5`.
* `taxonomy` — source taxonomy. Default `post_tag`.
* `exclude` — comma-separated term IDs to skip, e.g. `exclude="12,34"`.
* `min_size` / `max_size` — smallest / largest text size (numbers). Defaults `0.8` / `2.0`.
* `unit` — size unit: `rem`, `em`, `px`, `pt`. Default `rem`.
* `color_a` / `color_b` — hex colors of the rarest / most popular tags. Defaults `#888888` / `#222222`.
* `show_count` — append the post count to each tag (`true` / `false`). Default `false`.
* `aria_label` — accessibility label for the cloud container. Default `Tag cloud`.
* `ttl_minutes` — cache lifetime in minutes. Default `720` (12 h).

= What is the cache lifetime (TTL) and what does it do? =

Clouddy caches the set of tags it queries (using the WordPress Transients API) so the database
is not queried on every page load. The cache lifetime (`ttl_minutes`) is how long that cached
set is kept before it is rebuilt from the database — default 720 minutes (12 hours). It is only
a safety net: the cache is also refreshed automatically whenever content changes (a post is
saved or deleted, or tags are added, edited or removed). You rarely need to change it; lower it
only if you want a tighter upper bound on how stale the cloud can be.

= The "random" order does not change on every page reload. Why? =

The order is computed in PHP when the page is rendered — Clouddy uses no JavaScript. If you use
a full-page caching plugin or a CDN (for example LiteSpeed Cache, WP Super Cache, W3 Total
Cache, or a host/CDN cache), the generated HTML — including that one random order — is stored
and served to visitors, so the order only changes when that page cache is regenerated. This is
expected for any server-rendered random content. To reshuffle on every view despite caching you
would need client-side randomization (JavaScript), which Clouddy intentionally avoids. Either
exclude that page from full-page caching, or accept that the order refreshes when the cache does.

== Changelog ==

= 0.5.4 =
* Fixed: the block editor preview is now styled correctly (tags are spaced and sized) — the stylesheet is also loaded in the editor, not only on the front end.

= 0.5.3 =
* Lowered the minimum requirements to WordPress 6.3 and PHP 8.0.
* Documentation, readme and metadata cleanup in preparation for the WordPress.org plugin directory.

= 0.5.2 =
* Hybrid mode fix: when the rare share is 0 (or equals the total number of tags), the cloud now respects the limit instead of fetching all tags.

= 0.5.1 =
* The minimum and maximum text size fields now accept two decimal places (step 0.01).

= 0.5.0 =
* Internationalization: the interface base language is now English, with bundled Polish (pl_PL), French (fr_FR), German (de_DE) and Spanish (es_ES) translations. Added the Domain Path header.

= 0.4.0 =
* Three new "lens" display orders: "Longest in the center" (by name length), "Most popular in the center" and "Rarest in the center" (by post count) — the chosen ranking in the middle, the rest toward both ends.
* Panel: the "Random" order option moved to the end of the list.

= 0.3.0 =
* Settings panel: clearer field names and a hint for each option.
* Tag source (taxonomy) as a dropdown of registered taxonomies — no need to type the name from memory.
* Exclusion blocklist as a tag search by name with chips — no manual IDs.
* Cache lifetime given in minutes; the setting actually affects the cache TTL.

= 0.2.0 =
* Split tag selection and display order into two independent settings (new "Order" field: by count, alphabetical, random).

= 0.1.0 =
* Plugin skeleton: bootstrap, autoload, lifecycle hooks.

== Upgrade Notice ==

= 0.5.4 =
Fixes the unstyled tag cloud preview in the block editor.

= 0.5.3 =
Lowered the minimum requirements to WordPress 6.3 and PHP 8.0. Recommended for all users.
