=== PollHive – Poll, Voting & Survey ===
Contributors: webech
Tags: poll, polls, voting, survey, contest
Requires at least: 6.4
Tested up to: 7.0
Requires PHP: 8.1
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Create polls, voting contests, and surveys for WordPress with live results, AJAX voting, analytics, scheduling, and automatic theme matching.

== Description ==

**A complete poll, voting, and survey plugin for WordPress.**

Create unlimited polls, run online voting contests, and gather opinions with fast AJAX voting, configurable results, and a built-in analytics dashboard. Every poll automatically adopts your active theme's own colors, so it looks like part of your site from the first vote — no CSS required.

= Why PollHive =

* **Secure, authenticated voting.** Every vote is tied to a logged-in WordPress account, with one-vote-per-person enforcement built in — so results mean something.
* **You control what visitors see, and when.** Results can stay hidden until someone votes, or until the poll closes — your choice, per poll.
* **On-brand automatically.** Theme color detection is built in — no settings screen full of color pickers required.
* **Nothing happens without your permission.** The REST API is off by default. Uninstalling keeps your data untouched unless you explicitly opt in to remove it.
* **Built for every visitor.** Keyboard-operable, ARIA-labeled, reduced-motion aware — not an afterthought.

= Quick Features =

✔ Unlimited polls & options
✔ Text or image polls (contest voting included)
✔ Single or multiple choice
✔ AJAX voting — instant, no page reload
✔ Logged-in, one-vote-per-person enforcement
✔ Optional vote changing
✔ Poll scheduling & automatic closing
✔ Results visible always, after voting, or after close — your choice
✔ Progress bars or a live pie chart (Chart.js)
✔ Automatic theme color matching
✔ Light / Dark / Auto display mode
✔ Categories & free-form tags
✔ Filterable, sortable poll archive — created automatically
✔ 5 shortcodes + native Elementor widget
✔ Share popover — 10 platforms, your pick of which
✔ Built-in analytics dashboard
✔ Drag-and-drop poll builder, no code
✔ Optional read-only REST API (off by default)
✔ Translation-ready, POT file included
✔ Full keyboard & screen-reader accessibility

= Detailed Features =

**Secure, authenticated voting**

Every vote is tied to a logged-in WordPress account, with one vote per person per poll — updatable if you allow vote changing, locked if you don't. Votes submit by AJAX, instantly, with no page reload, so results reflect real people, not repeat clicks.

**You decide when results go public**

Always visible, visible only after voting, or only after the poll closes — set site-wide or per individual poll. It's enforced the same way everywhere: on the page, in AJAX responses, and in the REST API if you turn that on.

**Results people actually read**

A progress-bar list, an interactive pie chart, or both with a tab switcher. Winners are called out automatically. A genuine tie is labeled as a tie — PollHive won't quietly invent a winner.

**On-brand automatically**

PollHive reads your theme's own primary color — Astra's Global Color Palette, or a block theme's theme.json accent — and derives the entire poll's palette from it, chart colors included. Every other theme gets a clean built-in fallback. Prefer a fixed look instead? Set Light, Dark, or Auto display mode in Settings.

**Image polls & contest voting**

Any option can carry a Media Library image, rendered as a photo grid automatically — ready for design contests, "pick your favorite" polls, or any visual choice.

**Scheduling that runs itself**

Set a poll to open at a future date and close automatically at an expiry date, checked hourly. Set it up once; it starts and stops on its own.

**Organized like your content**

Categories (hierarchical, with their own admin screen) and free-form tags (created inline while building a poll). A filterable, sortable poll archive page — status, category, tag filters, Newest / Most Voted / Trending sort — is created automatically the moment you activate the plugin.

**A poll and survey maker that works anywhere**

A drag-and-drop builder creates the poll; five shortcodes place it — a specific poll, an auto-picked latest/random/popular poll, or the full archive — in any page, post, or widget area, in the Block Editor or Classic Editor. A native Elementor poll widget is available too, if Elementor is your builder — it's an option, not a requirement.

**Share without leaving the page**

A built-in popover for Facebook, X, WhatsApp, LinkedIn, Telegram, Reddit, Pinterest, Threads, email, and copy-link. Turn on only the platforms you want.

**Real analytics, not just a vote count**

Vote trends over time, desktop/mobile/tablet breakdown, top-performing polls, and a live recent-votes feed — from your wp-admin dashboard, no separate plugin required.

**Nothing hidden, nothing forced**

The REST API is read-only and off until you enable it — and what it returns still respects each poll's own results-visibility setting. Uninstalling leaves your data untouched unless you explicitly opt in to full cleanup.

= Perfect For =

* Community websites and member polls
* Customer feedback and product research
* Image contests and design voting
* Educational and classroom opinion polls
* Sports clubs and fan polls
* Internal team decisions
* Opinion polls embedded in blog posts

= Works Great With =

* **WordPress 6.4+** — no dependencies required to run
* **Any WordPress theme** — automatic color matching for Astra and block themes, a clean fallback for everything else
* **The Block Editor and Classic Editor** — shortcodes work in either
* **Elementor** — a native poll widget, if you use it (not required)
* **Any shortcode-compatible page builder** — PollHive's display is shortcode-based at its core, so it places wherever a WordPress shortcode can go

Additional native integrations are on the roadmap and are not part of the current version.

**PollHive is free to install and takes minutes to set up. Add the plugin, create your first poll, and start collecting real, authenticated votes today.**

== Installation ==

**Requirements:** WordPress 6.4+, PHP 8.1+.

1. Upload the `pollhive` folder to `/wp-content/plugins/`, or install through **Plugins → Add New** by searching "PollHive".
2. Activate the plugin. It automatically creates its database tables and a "Polls" archive page (or adopts an existing page containing the `[pollhive_archive]` shortcode).
3. Go to **PollHive → Add New**, add a title and two or more options, publish.
4. Display it: paste the shortcode into any page, post, or widget — `[pollhive id="123"]` — or use the Elementor widget, or link to the poll's own automatic page.
5. Optional: visit **PollHive → Settings** to adjust voting rules, results visibility, and share platforms. Every setting has a working default.

== Frequently Asked Questions ==

= Can guests vote without an account? =

Voting requires a logged-in WordPress account, which is what makes one-vote-per-person enforcement reliable. Guest voting is under consideration for a future release.

= Can someone change their vote? =

Yes, if allowed — site-wide or per poll. Their old vote is replaced, never duplicated.

= When do results become visible? =

Your choice: always, only after voting, or only after the poll closes. Site-wide default, overridable per poll.

= Bar chart or pie chart? =

A progress-bar list, an interactive pie chart (Chart.js), or both with a tab switcher — set under Settings > Results.

= Is PollHive an Elementor plugin? =

No. It's a standalone WordPress poll, voting, and survey plugin that works on any theme via shortcodes. A native Elementor widget is available as one option, not a requirement.

= Does PollHive have a native Gutenberg block? =

Not yet. The `[pollhive]` shortcode already works inside the Block Editor's Shortcode block. Additional native integrations may be added in future releases.

= Does it create pages automatically? =

Yes — a filterable "Polls" archive page on activation (or it adopts an existing one), plus an automatic page for every individual poll.

= Will it match my theme's colors? =

Automatically, for Astra's Global Color Palette and any block theme with a theme.json primary color. Every other theme gets a built-in fallback accent.

= Does it support categories and tags? =

Yes, both native WordPress taxonomies, with automatic filters on the poll archive.

= Can visitors share a poll? =

Yes — a share popover covering 10 platforms, each toggleable in Settings.

= Is there a REST API? =

Yes, read-only, off by default. What it returns still respects each poll's results-visibility setting.

= Where is poll data stored? =

Dedicated database tables for polls, options, and votes, plus native WordPress taxonomies for categories and tags.

= What happens to my data if I uninstall? =

Nothing, by default. Enable "Remove data on uninstall" under Settings > General first if you want a full cleanup.

= Does it support image or contest-style polls? =

Yes — any option can carry a Media Library image, rendered as a photo grid automatically.

= Is PollHive translation-ready? =

Yes — a complete POT file ships with the plugin, with a consistent text domain throughout.

= Is PollHive accessible? =

The share dialog is fully keyboard-operable, interactive elements carry ARIA labels, and the plugin respects visitors' reduced-motion preference.

= How do I get support? =

Email contact@webech.com, or use the Support link on the PollHive dashboard in wp-admin.

== Screenshots ==

1. The single-poll page — header stats, voting form, and related polls, created automatically.
2. Image/contest poll voting — Media Library images in a two-column grid with a selection badge.
3. Live results — progress bars with automatic winner detection, plus the pie chart view.
4. The filterable poll archive — status, category, and tag filters with three sort options.
5. The admin dashboard — recent and popular polls, a 30-day activity chart, a getting-started checklist.
6. The poll builder — drag-and-drop options, a Media Library image picker, tabbed settings.
7. The Analytics screen — vote trends, device breakdown, top polls, and a live votes feed.

== Changelog ==

= 1.0.0 =

**Polls & Voting**
* Initial public release.
* Text and image polls, single- or multiple-choice, with scheduling and automatic closing.
* Live AJAX voting with vote-changing support and optional rate limiting.

**Results**
* Progress-bar and pie chart (Chart.js) result views, with per-poll visibility rules.

**Pages & Display**
* Dedicated single-poll pages and a filterable, sortable poll archive.
* Five shortcodes and a native Elementor widget.
* Automatic theme color adoption (Astra Global Colors, block-theme theme.json palettes).
* Share popover with configurable platforms.

**Organization**
* Poll categories and tags, both native WordPress taxonomies.

**Admin**
* Dashboard, Analytics, poll builder, and Categories screens.

**Developer**
* Optional read-only REST API, off by default.

**Compliance & Quality**
* Full internationalization (translation-ready, POT file included).
* Accessibility: keyboard-operable dialogs, ARIA labeling, reduced-motion support, WCAG AA contrast.

== Upgrade Notice ==

= 1.0.0 =
First stable release.
