=== Elmspur Cascade – Dropdown Redirect ===
Contributors: Elmspur
Tags: cascading dropdown, dropdown redirect, dependent dropdown, block editor, redirect
Requires at least: 6.2
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.5.0
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Add a cascading dropdown to WordPress that redirects visitors on selection — no form builder needed.

== Description ==

Elmspur Cascade adds a cascading dropdown redirect block to the WordPress block editor. Visitors pick from one or more dependent dropdowns — for example Category → Topic → Page — and are redirected to the URL attached to their final choice. No form plugin or shortcode is required.

Each dropdown filters the next: choosing a value in one level determines the options available in the next. When the visitor reaches an item that has a URL, they are sent to it — either immediately, or after clicking a button you can label yourself.

= Features =

* **Native block** — works in posts, pages, the Site Editor, templates, template parts, and block widget areas. Compatible with FSE/block themes.
* **Visual tree builder** — point-and-click interface to add, edit, nest, and reorder dropdown items without touching JSON.
* **Up to 5 levels** of dependent dropdowns. Branches don't have to reach the maximum; a 2-level branch redirects from level 2 and remaining dropdowns stay disabled.
* **Redirect immediately** on final selection, or show a button the visitor clicks to go.
* **Open in a new tab** option.
* **Custom placeholder text** for each level.
* **Dark mode support** — choose Theme default, Light, Dark, or Auto (follows the visitor's system light/dark setting) for the dropdowns, and set custom dropdown text and background colors (with a separate dark-mode pair in Auto).
* **Navigation block variant** — a compact version that lives inside the core Navigation block, inline with your other menu links.
* Wide and full alignment support; inherits your theme's button styles.
* No form builder required. No shortcodes. No build step.

= Use cases =

* **Support sites:** Product → Issue Type → Help article
* **Multi-location businesses:** Country → City → Location page
* **Course sites:** Subject → Course → Lesson

= Companion add-on =

A separate add-on, distributed from elmspur.com (not from WordPress.org), adds saved/reusable dropdown trees: define a tree once, link it to as many blocks as you like, and edits propagate site-wide. It is optional — this plugin is fully functional on its own.

== Installation ==

1. In wp-admin go to **Plugins → Add New Plugin** and search for **Elmspur Cascade** — or download the zip and use **Upload Plugin**.
2. Activate the plugin.
3. Edit any post, page, or template and insert the **Cascading Redirect Dropdowns** block.
4. Click **Open menu builder** in the block sidebar to build your dropdown tree, adding a URL to each item that should be a destination.

== Frequently Asked Questions ==

= The dropdown text is invisible on my dark theme. How do I fix it? =
Some dark themes set light text but leave the browser's white dropdown background. Select the block, open "Dropdown colors" in the sidebar, and set Color mode to Dark (or Auto if your site follows the visitor's system setting). You can also pick exact colors under "Custom dropdown colors".

= Does this require a form plugin? =
No. Elmspur Cascade is a standalone native block with no dependencies. Install and activate it, and the block is immediately available in the editor.

= How many dropdown levels can I have? =
Up to 5 cascade levels. Each branch only renders as many dropdowns as it actually uses — a 2-level branch redirects from level 2 and leaves remaining dropdowns disabled.

= Does it work with my theme? =
Yes. It's a native WordPress block that inherits your theme's styles. The Go button uses the core button element, so it picks up your theme's button colors, typography, and border radius automatically.

= Does it slow my site down? =
No. The front-end script is small and dependency-free — no jQuery, no external requests. It uses `viewScript` in block.json, so it only loads on pages that actually contain the block.

= Can the final selection open in a new tab? =
Yes. Toggle **Open in a new tab** in the block sidebar.

== Screenshots ==

1. The visual menu tree builder in the block editor — add, edit, nest, and reorder dropdown items without touching JSON.
2. The cascading dropdowns on the front end — each selection filters the next level, and the final choice redirects the visitor.

== The JSON format ==

An array of items. Each item has a "label" and either "children" (an array of more items) or a "url".

[
  {
    "label": "Category A",
    "children": [
      {
        "label": "Subcategory A1",
        "children": [
          { "label": "Page one",  "url": "https://example.com/a/a1/one" },
          { "label": "Page two",  "url": "https://example.com/a/a1/two" }
        ]
      }
    ]
  }
]

== Settings (block sidebar) ==

* Menu data — the JSON hierarchy (also editable via the visual tree builder).
* Redirect immediately on final selection — skip the Go button.
* Open in a new tab.
* Button label.
* Placeholder text for each level.

== Changelog ==

= 1.5.0 =
* New: "Dropdown colors" setting — Theme default, Light, Dark, or Auto (follows the visitor's system light/dark preference). Fixes white-on-white dropdown text on dark themes.
* New: custom dropdown text and background colors, with a separate dark-mode pair when using Auto. Picking only one color of a pair fills in a contrasting partner so text always stays readable. Theme palette colors are supported.

= 1.4.1 =
* Fix: on Safari and iOS, "Redirect immediately" could fail to navigate because WebKit does not treat a dropdown change as a user gesture (and blocks new-tab redirects as popups). These browsers now automatically show the Go button as a click-to-go fallback; all other browsers are unchanged.
* Fix: stacked dropdowns no longer render as oversized boxes on narrow screens.

= 1.4.0 =
* Cascade depth is no longer gated behind a license — menus can use up to 5 dependent levels for everyone, both in the visual builder and on the front end.
* Renamed to Elmspur Cascade – Dropdown Redirect.
* Readme: clarified feature descriptions.

= 1.3.1 =
* Security: URL values in dropdown trees are now sanitized server-side with esc_url_raw() before output; javascript: URIs and other non-safe schemes are also blocked client-side in view.js as defence-in-depth.
* Code: Removed an orphaned/unclosed comment block that was merging into the crd_tree_depth docblock.
* Block: Default example URLs in block.json replaced with example.com placeholders.
* Readme: Added FAQ section; installation instructions updated.

= 1.3.0 =
* Levels are now dynamic: the block renders one dropdown per level your menu actually uses (a 2-level menu shows 2 dropdowns).
* New crd_menu_data extensibility filter and a savedMenuId attribute.
* No changes required to existing blocks.

= 1.2.0 =
* New: "Cascading Dropdowns - Menu Item" companion block. Open the Navigation block in the Site Editor, click +, and insert it inline between your menu links. Compact styling sized to nav bars; auto-redirect on by default; stacks vertically inside the mobile menu overlay.
* Both blocks share the same tree builder, settings, and data format.

= 1.1.0 =
* New: point-and-click menu tree builder. Select the block and click "Open menu builder" (sidebar) or "Edit menu tree" (canvas). Add, edit, reorder, nest, and delete items without touching JSON.
* The JSON editor moved to a collapsed "Advanced (JSON)" panel. Data format is unchanged — blocks created with 1.0.0 work as-is.

= 1.0.0 =
* Initial release.
