=== Clouddy ===
Contributors: jaclas
Donate link: https://paypal.me/lasjac
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.6
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.

= How do I style the tag cloud? (CSS classes and variables) =

The markup is clean, low-specificity HTML — style it with regular CSS in your theme, a page builder (e.g. Bricks), or Appearance → Customize → Additional CSS. No `!important` needed.

Generated HTML:

    <nav class="clouddy"
         style="--clouddy-min:0.8rem; --clouddy-max:2rem;
                --clouddy-color-a:#888888; --clouddy-color-b:#222222">
      <a class="clouddy-tag" href="..." style="--clouddy-weight:0.73">
        name <span class="clouddy-count">(24)</span>
      </a>
      ...
    </nav>

CSS hooks:

* `.clouddy` — the container (`<nav>`, flex). Holds the variables `--clouddy-min`, `--clouddy-max`, `--clouddy-color-a`, `--clouddy-color-b`.
* `.clouddy-tag` — a single tag (`<a>`). Holds `--clouddy-weight` (0–1 per tag — do not override it).
* `.clouddy-count` — the post count (`<span>`, shown only when "Show post count" is on).

Size and color are computed from the variables on the container. To change the scale or the colors while keeping the popularity-based effect, override those variables — not `font-size`/`color` on the tag.

Size range (keeps popularity scaling):

    .clouddy {
        --clouddy-min: 1rem;   /* rarest tag */
        --clouddy-max: 3rem;   /* most popular tag */
    }

Do not set `font-size` on `.clouddy-tag` — that disables the scaling. Use `--clouddy-min`/`--clouddy-max`.

Colors (a smooth `color-mix(in oklch …)` is computed between the two ends — you only set the extremes):

    .clouddy {
        --clouddy-color-a: #94a3b8;   /* rarest */
        --clouddy-color-b: #0ea5e9;   /* most popular */
    }

Layout and spacing:

    .clouddy {
        gap: 0.5rem 1rem;
        justify-content: center;
    }

"Pill" tags (does not touch size scaling):

    .clouddy-tag {
        padding: 0.2em 0.6em;
        border-radius: 999px;
        background: #f1f5f9;
    }

One flat color instead of the gradient:

    .clouddy-tag { color: #333; }

Hover zoom that is stronger for rarer (smaller) tags, using `--clouddy-weight`:

    .clouddy-tag {
        transition: transform .25s ease;
    }
    .clouddy-tag:hover {
        transform: scale(calc(1.06 + (1 - var(--clouddy-weight, 0.5)) * 0.18));
    }

Here `1.06` is the zoom every tag gets and `0.18` is the extra added to the rarest; both are free to tune.

= Can I replace the default stylesheet entirely? =

Yes. The default stylesheet (handle `clouddy`) loads on the front end and in the block editor preview (hook `enqueue_block_assets`). To style from scratch without it, dequeue it on the same hook (Code Snippets or your theme's functions.php):

    add_action( 'enqueue_block_assets', function () {
        wp_dequeue_style( 'clouddy' );
    }, 20 );

The `--clouddy-weight` variables stay in the HTML, so you can build your own `calc()` / `color-mix()` formula or ignore scaling.

= 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.

== Screenshots ==

1. Tag cloud with a color gradient and post counts.
2. Tag cloud styled as pills; size and color scale with tag popularity.
3. Clouddy in use on a live site.
4. The global settings panel (under Settings).

== Changelog ==

= 0.5.6 =
* Settings page now shows the plugin version and release date at the top.
* Settings page now shows how many tags exist in total and how many are unused (no posts), with an expandable list of the unused tags, next to the "Total number of tags" field.

= 0.5.5 =
* Added a "Support development" link (with a heart icon) on the settings page.
* Removed the bundled Polish, German and Spanish translations — they are now delivered automatically through WordPress.org. French stays bundled.

= 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.6 =
The settings page now shows the plugin version/release date and tag stats (total and unused tags).

= 0.5.5 =
Adds a support link on the settings page; Polish, German and Spanish translations now come from WordPress.org.

= 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.
