=== CC Popular Categories ===
Contributors: EJS Corp Pty Ltd
Requires at least: 6.0
Tested up to: 6.8
Requires PHP: 7.4
Stable tag: 3.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Shortcode-based featured promotional banner plus a WooCommerce product
category grid, configured entirely from the WordPress admin.

== Description ==

Render the component anywhere with:

    [popular_categories]

All configuration lives in WooCommerce > Popular Categories. The shortcode
reads the saved settings; no shortcode parameters are required.

The plugin never injects itself into wp_head, wp_footer,
woocommerce_before_main_content or any other global hook. The component
appears only where the shortcode is placed.

= Admin tabs =

1. Featured Banner - status, content, button, price, image, colours, design,
   background pattern and bottom hazard stripe.
2. Category Sorting - search, filters, selection, drag-and-drop ordering,
   plus the category card display settings.

The drag-and-drop order is stored only for this plugin. WooCommerce category
archives, menus, widgets and other plugins are never affected.

= Optional dependencies =

* WooCommerce - required for the category grid. Without it the banner still
  renders and an admin notice explains the situation. No fatal error.
* ACF - optional. When present, the `icon_cover_fly` field attached to a
  product category is used as a hover flyout image. Without ACF the flyout is
  simply omitted.

== Shortcode attributes ==

All attributes are optional and override the saved admin settings for that
one instance. Supported for backward compatibility:

show_promo, promo_label, promo_title, promo_desc, promo_btn, promo_url,
promo_from_label, promo_price, promo_img, promo_img_alt, taxonomy,
popular_key, mode, popular_value, image_size, hide_empty, orderby, order,
limit, button_text, desc_words, heading, show_count, show_desc, show_button,
show_flyout, columns, include, categories, exclude.

Examples:

    [popular_categories]
    [popular_categories show_promo="false"]
    [popular_categories limit="8" columns="4"]
    [popular_categories include="12,34,56"]
    [popular_categories categories="safety-signs warning-signs"]

== Template overrides ==

Copy any file from the plugin's templates/ folder into:

    wp-content/themes/<your-theme>/cc-popular-categories/

== Filters ==

* ccpc_settings              - resolved plugin settings
* ccpc_shortcode_settings    - settings for a single shortcode instance
* ccpc_display_categories    - prepared category card data
* ccpc_shortcode_html        - final rendered markup
* ccpc_admin_capability      - capability required to manage the plugin
* ccpc_force_enqueue_assets  - force-enqueue frontend CSS on a given view

== Uninstall ==

Removes only this plugin's own options and transients. WooCommerce
categories, products, media, ACF fields and other plugin data are never
touched.

== CMS sections (admin tabs 3-6) ==

Four additional sections, each with its OWN standalone shortcode. They are
completely independent of Tab 1 / Tab 2 and store their data in separate
options, so the Featured Banner and Category Sorting data is never touched.

Tab 3 - Hero / Business Information   [ccpc_hero]     or [dtc_section_3]
Tab 4 - Latest Offers                 [ccpc_offers]   or [dtc_section_4]
Tab 5 - Best of the Best              [ccpc_best]     or [dtc_section_5]
Tab 6 - Legend Cards                  [ccpc_legends]  or [dtc_section_6]

Every section supports: enable/disable, editable tab name, section ID, custom
CSS class, container width (px/%/rem/em/vw), background colour, text colour
and top/bottom padding.

Repeaters (all unlimited, with add / duplicate / delete / drag-reorder /
collapse / enable-disable):

* Hero Rows      - image, heading, rich text, button, per-row layout
                   direction (image left or right), image link, caption
* Offers         - image, title, description, URL, button text, new tab
* Showcase Items - image, number, title, description, badge, rotation,
                   vertical offset, top-pick flag
* Features       - number (auto or manual), title, description, icon, URL
* Content Blocks - heading, rich text, image, button, URL
* Legend Cards   - icon, number (auto or manual), title, subtitle,
                   description, URL, per-card accent colour, icon background

Legend Cards carousel: the track uses native CSS overflow-x with scroll-snap,
so touch swipe and trackpad scrolling work without JavaScript. Arrows, dots,
mouse dragging and the optional gentle auto-scroll are progressive
enhancements. Arrows and dots only appear when the cards actually overflow.
Auto-scroll pauses on hover, focus, touch and wheel, and never runs for
visitors who prefer reduced motion. Horizontal overflow is contained in the
track, so the page itself never scrolls sideways.

Section data is stored in ccpc_section_hero, ccpc_section_offers,
ccpc_section_best and ccpc_section_legends.

Section filters: ccpc_section_data, ccpc_section_render_data,
ccpc_section_html, ccpc_force_enqueue_section_assets.

== Typography ==

This plugin never ships a font stack. Every section declares
font-family: inherit, including on buttons, inputs, selects and links, which
do not inherit it by default in any browser. The typeface therefore always
comes from the theme's html/body rules.

== Button hover ==

The default hover state for every button in the plugin is a black background
with white text. Each one remains fully configurable from the admin:

* Tab 1 - Button Hover Background / Button Hover Text
* Tab 2 - Card Button Hover Background / Card Button Hover Text
* Tab 3 - Button Hover Background / Button Hover Text
* Tab 4 - Button Hover Background / Button Hover Text
* Tab 5 - Button Hover Background / Button Hover Text (blocks and showcase),
          plus a separate pair for the CTA banner buttons
* Tab 6 - Card Hover Background / Card Hover Text, applied only when
          "Invert card colours on hover" is switched on

== Changelog ==

= 3.1.0 =
* Tab 5: added the CMS-managed dark call-to-action banner with hazard stripe,
  eyebrow, headline, highlighted headline and two configurable buttons.
  Switched off by default so it never appears on an existing site unannounced.
* All buttons now default to a black hover background with white text, and
  every hover pair is configurable.
* Removed the last hardcoded font stack; all sections inherit the theme font.
* Tab 2 gained its own enable/disable toggle, matching the other tabs.

= 3.0.0 =
* Added admin tabs 3-6 with four standalone shortcodes.
* Unlimited repeaters with drag-reorder, duplicate and collapse.
* Legend Cards horizontal carousel with arrows, dots, swipe and keyboard.
* Container width units extended with rem and em for the new sections.
* Tabs 1 and 2 unchanged; their data is stored in separate options.

= 2.1.0 =
* Maximum Width and the three Image Width fields now accept px, % or vw.
* The selected unit drives the validation range as well as the CSS output, so
  a percentage value is never clamped against the pixel bounds.
* Existing installs upgrade with no migration: any width saved before this
  release keeps its value and is treated as px.

= 2.0.0 =
* Rebuilt as a structured, admin-configurable plugin.
* Two-tab admin interface with drag-and-drop category ordering.
* Dynamic colours via CSS custom properties.
* Media Library integration for the banner image.
* AJAX saving with nonce and capability verification.
