=== WebCalendar ===
Contributors: agenticdaisy
Tags: event calendar, calendar, events, scheduling, ical
Requires at least: 6.6
Tested up to: 6.9
Requires PHP: 8.1
Stable tag: 1.0.7
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A modern calendar plugin with recurring events, iCal import/export, remote calendar sync, Gutenberg blocks, and access control.

== Description ==

WebCalendar gives your WordPress site a clean, responsive calendar with the features you actually need — recurring events, iCal import, remote sync, email reminders, and fine-grained permissions — without the complexity.

**Calendar Views & Display**

* Month, week, and day views with smooth AJAX navigation — no page reloads
* Responsive design that adapts to any theme and screen size
* Color-coded categories for visual organization
* Gutenberg blocks (Calendar + Upcoming Events) and `[webcalendar]` shortcode

**Event Management**

* Recurring events — daily, weekly, monthly, and yearly patterns with RRULE support
* Edit a single instance or the entire series
* File attachments via the WordPress Media Library
* Conflict detection warns you about overlapping events
* Public, Private, and Confidential visibility levels

**Import, Export & Sync**

* Import `.ics` files from Google Calendar, Outlook, Apple Calendar, or any iCal source
* Export your calendar in iCalendar format
* Subscribe to remote iCal feeds with automatic hourly sync
* Import public holidays for any country

**Collaboration & Permissions**

* Invite WordPress users to events with email notifications
* Event reminders via WP-Cron
* 36 granular capabilities mapped to WordPress roles — control who can view, create, edit, and manage events

**SEO & Sharing**

* Single event pages with SEO-friendly permalinks
* Schema.org Event JSON-LD, Open Graph, and Twitter Card meta tags
* Social share buttons and "Add to Google/Outlook/Yahoo" one-click buttons

**For Developers**

* Full REST API for events, categories, holidays, and remote calendars
* Built on Clean Architecture with `webcalendar-core` business logic library
* PSR-4 autoloading, PHPStan Level 9, 1100+ automated tests
* All calendar data in dedicated `webcal_*` tables — no Custom Post Types

**Want Even More?**

[WebCalendar Pro](https://agenticdaisy.com/webcalendar/) is a separate premium plugin that adds:

* **Appointment Booking** — public scheduling with availability management
* **Google & Outlook Sync** — two-way OAuth synchronization
* **Multisite Network Support** — shared calendars across a WordPress network
* **White-Labeling** — remove all WebCalendar branding
* **Priority Support** — 24-hour response time SLA

The free version you're using right now is fully functional with zero locked features. Pro adds capabilities that aren't included here.

**Technical Note: Database Architecture**

This plugin integrates `webcalendar-core`, a framework-agnostic Composer library that provides all calendar business logic (events, recurrence, iCal, permissions) through 17 repository classes. These repositories require PDO and use exclusively parameterized prepared statements — no raw SQL concatenation. WordPress-specific data (users, options, capabilities) is accessed via `$wpdb` through the plugin's Bridge layer (`WpUserRepository`, `WpConfigRepository`, etc.). See `src/Bridge/PdoFactory.php` for the connection factory.

== Installation ==

1. Upload the `agenticdaisy-calendar` folder to `/wp-content/plugins/`
2. Activate the plugin through the "Plugins" menu in WordPress
3. Navigate to **WebCalendar** in the admin sidebar to view the calendar
4. Go to **WebCalendar > Settings** to configure time format, date format, and other options
5. Use the `[webcalendar]` shortcode or the **WebCalendar** Gutenberg block to display the calendar on any page

**Requirements:**

* PHP 8.2 or higher
* WordPress 6.6 or higher
* MySQL 5.7+ or MariaDB 10.3+

== Frequently Asked Questions ==

= How do I display the calendar on a page? =

Use the `[webcalendar]` shortcode or add the **WebCalendar Calendar** block in the block editor. Both support AJAX navigation between months without page reloads.

= Can I import events from Google Calendar? =

Yes. Export your Google Calendar as an `.ics` file and use **WebCalendar > Import** to import it. You can also use **WebCalendar > Remote Calendars** to subscribe to a public Google Calendar iCal URL for automatic syncing.

= How do I migrate from another calendar plugin? =

Export your existing calendar as an `.ics` file (most calendar plugins support this), then import it via **WebCalendar > Import**. This works with any plugin or service that exports standard iCalendar files.

= Does the plugin support recurring events? =

Yes. When creating or editing an event, use the recurrence builder to set daily, weekly, monthly, or yearly patterns. You can edit individual instances or the entire series.

= What happens to my data if I uninstall the plugin? =

By default, all calendar data is preserved when you uninstall. To delete all data on uninstall, enable the "Delete Data on Uninstall" option in **WebCalendar > Settings**.

= Can different users have different permissions? =

Yes. The plugin registers 36 capabilities mapped to WordPress roles. Administrators can manage all settings and events, Editors can manage events and categories, and Authors can create and manage their own events.

= Does it work with page builders like Elementor or Divi? =

Yes. Use the `[webcalendar]` shortcode inside any page builder. The calendar renders responsively inside any container.

= Does the calendar work with my theme? =

The calendar uses standard WordPress styles and adapts to your theme's container width. It is designed to be responsive and works on desktop, tablet, and mobile.

= What is your versioning and compatibility policy? =

WebCalendar follows [Semantic Versioning](https://semver.org/). Patch releases (1.0.x) contain bug fixes only. Minor releases (1.x.0) add features without breaking existing functionality. Major releases may include breaking changes and will be documented in the changelog. The REST API is versioned (`/v1/`) and will not introduce breaking changes within a major version. Security vulnerabilities should be reported to security@agenticdaisy.com — see [Security Policy](https://agenticdaisy.com/security/) for our disclosure policy.
== External Services ==

This plugin connects to the following third-party services:

= Nager.Date API =
Used for importing public holidays via WebCalendar > Holidays.
* Endpoint: https://date.nager.at/api/v3/
* [Terms of Use](https://date.nager.at/LegalNotice)
* [Privacy Policy](https://date.nager.at/Privacy)

= Google Calendar Public Feeds =
Alternative holiday source. Fetches public .ics files from Google.
* Endpoint: https://calendar.google.com/calendar/ical/
* [Google Privacy Policy](https://policies.google.com/privacy)
* [Google Terms of Service](https://policies.google.com/terms)

= Thunderbird Holiday Calendars =
Alternative holiday source via community-maintained .ics files.
* Endpoint: https://www.thunderbird.net/media/caldata/
* [Mozilla Terms of Use](https://www.mozilla.org/about/legal/terms/mozilla/)
* [Mozilla Privacy Policy](https://www.mozilla.org/privacy/)

= Remote Calendar Sync (User-Configured) =
When remote iCal subscriptions are configured, the plugin fetches .ics data from
those URLs via HTTP GET. No user data is transmitted to these services.

= OpenStreetMap / Nominatim =
When a single event page has a location and the map provider is set to OpenStreetMap
(the default), the plugin geocodes the address via the Nominatim API and displays a
map using OpenStreetMap tile servers. The event location string is sent as a search
query. No user personal data is transmitted.
* Geocoding endpoint: https://nominatim.openstreetmap.org/search
* Tile server: https://tile.openstreetmap.org/
* [OpenStreetMap Terms of Use](https://wiki.osmfoundation.org/wiki/Terms_of_Use)
* [Nominatim Usage Policy](https://operations.osmfoundation.org/policies/nominatim/)
* [OpenStreetMap Privacy Policy](https://wiki.osmfoundation.org/wiki/Privacy_Policy)

= Google Maps Embed API =
When the map provider is set to Google Maps in settings, single event pages display
an embedded Google Map for the event location. The event location string and your
Google Maps API key are sent to Google. No other user data is transmitted.
* Endpoint: https://www.google.com/maps/embed/v1/place
* [Google Maps Platform Terms of Service](https://cloud.google.com/maps-platform/terms)
* [Google Privacy Policy](https://policies.google.com/privacy)

= Add to Calendar Links =
Single event pages include "Add to Calendar" buttons that generate links to Google
Calendar, Outlook.com, and Yahoo Calendar. When a visitor clicks a button, the event
title, date, time, location, and description are passed as URL parameters to the
chosen service. No data is sent until the visitor clicks.
* Google Calendar: https://www.google.com/calendar/render — [Terms](https://policies.google.com/terms) | [Privacy](https://policies.google.com/privacy)
* Outlook.com: https://outlook.live.com/calendar/0/action/compose — [Terms](https://www.microsoft.com/servicesagreement) | [Privacy](https://privacy.microsoft.com/privacystatement)
* Yahoo Calendar: https://calendar.yahoo.com/ — [Terms](https://legal.yahoo.com/us/en/yahoo/terms/otos/index.html) | [Privacy](https://legal.yahoo.com/us/en/yahoo/privacy/index.html)

= Social Sharing Links =
Single event pages include social sharing buttons for Facebook, X (Twitter), and
LinkedIn. When a visitor clicks a button, the event page URL and title are passed as
URL parameters to the chosen service. No data is sent until the visitor clicks.
* Facebook: https://www.facebook.com/sharer/sharer.php — [Terms](https://www.facebook.com/terms.php) | [Privacy](https://www.facebook.com/privacy/policy/)
* X (Twitter): https://x.com/intent/tweet — [Terms](https://x.com/tos) | [Privacy](https://x.com/privacy)
* LinkedIn: https://www.linkedin.com/sharing/share-offsite/ — [Terms](https://www.linkedin.com/legal/user-agreement) | [Privacy](https://www.linkedin.com/legal/privacy-policy)

== Development & Source Code ==

Full unminified source for this plugin is included in this distribution under GPL-2.0-or-later — you do not need to download anything external to rebuild the compiled assets.

**What ships in this zip:**

* `src/` — unminified React/JSX source for all admin components, frontend calendar, and the mini-calendar widget
* `build/` — the pre-compiled minified bundles (what the plugin actually loads at runtime)
* `package.json` + `package-lock.json` — Node build manifest and lockfile for reproducible `npm install`
* `composer.json` — PHP dependency manifest

**Rebuilding the compiled assets from source:**

Prerequisites: PHP 8.2 or higher with Composer 2, Node.js 20 or higher with npm 10.

1. `composer install` — install PHP dependencies
2. `npm install` — install JavaScript build dependencies (@wordpress/scripts, React, Toast UI Calendar, Leaflet, Tiptap)
3. `npm run build` — compile `src/index.js` and `src/frontend.js` into the minified bundles under `build/`

The compiled output in `build/` is byte-reproducible from the matching `src/` at the same version using this toolchain.

== Screenshots ==

1. Frontend month view — responsive calendar embedded on any page with color-coded events
2. Frontend week view — detailed weekly schedule with timed events and all-day items
3. Single event page — SEO-friendly permalink with map, social sharing, and add-to-calendar buttons
4. Mobile responsive — calendar adapts to any screen size with touch-friendly navigation
5. Admin calendar — full month view with color-coded categories and quick event management
6. Event editor — recurring events, categories, visibility, participants, and file attachments
7. Category management — color picker with event counts and bulk merge
8. Remote calendars — subscribe to external iCal feeds with automatic sync
9. Settings page — status dashboard with event counts, sync status, and configuration options

== Changelog ==

= 1.0.7 =
* Feat: Import page now shows collapsible "Supported fields" reference tables for both iCal and CSV tabs, so users can see which properties are recognised without leaving the page.
* Fix: Global holiday import (Nager.Date) now imports the current year plus the next two years in a single operation, instead of only importing the current year.
* Fix: Thunderbird holiday provider URLs corrected — files are now fetched from the correct GitHub location with the correct filename prefixes.
* Fix: Calendar now respects the WordPress "Week Starts On" setting (Settings → General) for month and week views.
* Fix: Shortcodes in event descriptions are now expanded when displaying events on single-event pages and in the REST API response.

= 1.0.6 =
* Fix: Lowered minimum PHP requirement from 8.2 to 8.1. The distributed build already passes PHP 8.1 syntax checks; the header constraint was unnecessarily blocking installs on hosts running PHP 8.1.

= 1.0.5 =
* Fix: iCal import time-zone conversion now actually runs. 1.0.4 shipped the core fix but did not pass the site time zone to the importer, so UTC (.ics "Z") and zoned times were still stored verbatim and imported events appeared shifted by the UTC offset (e.g. 1 hour during British Summer Time). The site time zone is now wired into the importer, so imported events land at the correct local time and day.

= 1.0.4 =
* Fix: iCal import now preserves event times across time zones. DTSTART/DTEND TZID values are forwarded on import, and UTC or zoned times are rebased to the calendar's time zone, so imported events no longer appear shifted by several hours.
* Bumped craigk5n/webcalendar-core to ^4.3.4 (includes the EventMapper time-zone import fixes).

= 1.0.3 =
* Fix: PdoFactory now parses DB_HOST the same way wpdb does — bare `localhost` resolves to a Unix socket, matching shared-hosting environments. Resolves PDOException [HY000] [2002] "Can't assign requested address" reported on plugin activation.
* Fix: Activation no longer aborts on database connection errors — data seeding (categories, holiday calendar, layer subscriptions) is wrapped in try/catch and queued for lazy retry on the next admin request.
* Fix: REST API validators for optional positive-int fields (category_id, featured_image_id, originalEventId) now accept `null`/`0`/`""` as "not provided" instead of returning HTTP 400. Resolves admin form save failures when no category was selected.
* Fix: REST `owner` validator accepts the empty-string "global owner" sentinel used by categories and nonuser calendars.
* Test: New WP_DEBUG E2E lane scans wp-content/debug.log around every test and fails on plugin-originated PHP notices/warnings/deprecations/fatals/PDOException/_doing_it_wrong. 39 critical-flow specs covering activation lifecycle, REST write paths, and rendering surfaces.
* Test: New socket-only MySQL activation lane reproduces the WP.org reviewer environment (MariaDB --skip-networking + DB_HOST=localhost) end-to-end as a regression guard.
* Bumped craigk5n/webcalendar-core to ^4.3.2 (includes PdoEventRepository::search() fix for reused :keyword named placeholder under native prepares).

= 1.0.2 =
* Security: remote-calendar sync and webhook delivery now use wp_safe_remote_* to block private-IP / cloud-metadata destinations (SSRF hardening)
* Security: admin file uploads (CSV and iCal import) now route through wp_handle_upload() with an explicit MIME allowlist; temp uploads are cleaned up via wp_delete_file()
* Security: added direct-file-access guards (defined('ABSPATH') || exit) to all directory index stubs
* Security: REST export-route _wpnonce inputs are sanitized via sanitize_text_field(wp_unslash()) before wp_verify_nonce()
* Security: REST write routes now declare explicit args schemas with per-field sanitize_callback and validate_callback on all 23 POST/PUT/DELETE endpoints across 8 controllers
* WP-CLI import/export commands now use WP_Filesystem instead of raw file I/O
* Added "Development & Source Code" readme section with build instructions for plugin reviewers
* Fixed: popup "View Event Details" link works with emoji event titles
* 1,038 automated tests (+23 new regression guards), PHPStan Level 9, 0 PHPCS errors on changed code
* WP.org Review Sprint #2 — all 11 findings from the third-pass review are resolved

= 1.0.1 =
* Single event pages now display participant list
* Calendar frontend fetches all pages of events (fixes missing events on busy days)
* Recurring event detail pages show correct occurrence date
* Plugin slug changed to `agenticdaisy-calendar` per WordPress.org review
* Added external service disclosures (OpenStreetMap, Google Maps, social sharing, add-to-calendar)
* Converted inline scripts to wp_add_inline_script() per WordPress coding standards
* Renamed wpApiSettings JS global to webcalApiSettings to avoid reserved wp_ prefix
* Bundled Leaflet locally instead of loading from CDN
* WordPress Plugin Check: 0 errors (all resolved)
* WordPress coding standards compliance fixes
* Added PDO usage documentation for plugin reviewers
* 1,126 automated tests, PHPStan Level 9, 86%+ coverage

= 1.0.0 =
* Initial release
* Full calendar admin UI with month/week/day views (Toast UI Calendar)
* Event CRUD via REST API with recurring events (RRULE support)
* Categories with color coding and layer-based calendar filtering
* iCal import/export and remote calendar subscription with automatic sync
* `[webcalendar]` shortcode and Gutenberg blocks (Calendar, Upcoming Events)
* Single event pages with SEO-friendly permalinks and Schema.org JSON-LD
* Open Graph and Twitter Card meta tags for social sharing
* Social share buttons and "Add to Google/Outlook/Yahoo" one-click buttons
* Global holiday management with standard US holiday import
* Conflict detection with "Save Anyway" option for overlapping events
* Email notification system with invitation templates and reminders
* Role-based access control (36 capabilities)
* All features fully unlocked — no license gating
* REST API rate limiting and event pagination with safety caps
* 1,126 automated tests, PHPStan Level 9

== Upgrade Notice ==

= 1.0.7 =
Fixes holiday import (Thunderbird URLs, Nager.Date multi-year), calendar start-of-week setting, and shortcode expansion in event descriptions. Adds supported-fields help text to the import page.

= 1.0.6 =
Lowers the minimum PHP requirement from 8.2 to 8.1.

= 1.0.5 =
Completes the 1.0.4 time-zone fix: imported iCal events using UTC or a different time zone now actually land at the correct local time. Recommended for anyone importing .ics calendars (especially if you imported on 1.0.4 and saw times off by an hour).

= 1.0.4 =
Fixes imported iCal events appearing at the wrong time when the source file uses UTC or a different time zone. Recommended for anyone importing .ics calendars.

= 1.0.3 =
Critical fix: plugin activation now succeeds on shared hosting with bare `DB_HOST=localhost`. Also fixes admin form save failures when no category was selected. Strongly recommended.

= 1.0.2 =
Security hardening across REST, uploads, and outbound HTTP. Recommended.

= 1.0.1 =
WordPress.org submission compliance fixes and plugin slug rename.

= 1.0.0 =
Initial release.
