=== Icalviz ===
Contributors:       killiansantos
Tags:               google calendar, availability, booking, ical, calendar
Requires at least:  5.8
Tested up to:       6.9
Stable tag:         1.0.0
Requires PHP:       7.4
License:            GPL-2.0-or-later
License URI:        https://www.gnu.org/licenses/gpl-2.0.html

Show your real-time Google Calendar availability as a beautiful front-end calendar — no API key, no coding required.

== Description ==

**Icalviz** connects to any public iCal feed and displays your availability day by day on any page or post, using a simple shortcode. Works with Google Calendar, Outlook, Apple Calendar, Nextcloud, and any service that exposes a public `.ics` link.

Each day is automatically classified:

* 🟢 **Free** — no events scheduled
* 🟡 **Partial availability** — some time slots are taken
* 🔴 **Fully booked** — your entire working hours are covered

Visitors can click any day to see occupied time slots in a clean timeline modal. Optionally display a **call-to-action button** (e.g. "Book this slot") that links to your booking system.

**Why Icalviz?**

Stop copy-pasting your schedule into a webpage. Connect your Google Calendar, Outlook, Apple Calendar, or any iCal-compatible calendar — Icalviz reads your public iCal feed and updates automatically, every 30 minutes.

= Use cases =

🏢 **Meeting room & shared space booking** — Display a room's availability calendar so your team or clients can instantly see open slots, without logging into any system.

📅 **Show your public availability as a freelancer or consultant** — Let potential clients see when you are free before they even reach out. Display months of availability from your Google Calendar, Outlook or any iCal feed in seconds.

🎓 **Training sessions & open office hours** — Show students or participants which session slots are still open. Mark them as full automatically when your agenda is blocked.

🏡 **Seasonal rental & short-stay property** — Display your gîte, studio, or vacation rental availability directly on your WordPress site, synced live from any iCal-compatible calendar.

🚗 **Fleet & equipment availability** — Track and display the availability of a shared vehicle, camera kit, or any bookable asset — simply by blocking time in Google Calendar, Outlook, or any other iCal calendar.

= Key features =

* **Zero configuration** — Paste your iCal URL, copy the shortcode, done.
* **No API key required** — Works with any public iCal feed: Google Calendar, Outlook, Apple Calendar, Nextcloud, and more.
* **Responsive** — 2 columns on desktop, 1 on mobile. Navigation arrows for multi-month views.
* **Timeline modal** — Click a day to see occupied time slots in a visual hourly timeline.
* **Call-to-action button** — Add a custom button (e.g. "Request a slot") inside the modal, linking to your booking page or contact form.
* **Custom labels** — Rename "Free", "Partial availability", "Fully booked" to match your vocabulary.
* **Dark mode** — Built-in light and dark themes.
* **Booking window** — Limit how many days ahead users can see (e.g. next 90 days only).
* **Onboarding wizard** — Step-by-step setup guides you from iCal URL to ready shortcode in under a minute.
* **Inline iCal tester** — Paste a URL and instantly see whether it connects, how many events it contains, and what the next upcoming events are.
* **Debug panel** — One-click diagnostic report covering WordPress environment, plugin version, cache status, iCal feed health, and slot calculation trace. Designed for quick support.

= How it works =

1. Get your public iCal URL (`.ics` link) from your calendar app:
   - **Google Calendar**: ⋮ → Settings and sharing → Make available to public → Public address in iCal format
   - **Outlook**: Calendar settings → Shared calendars → Publish → ICS link
   - **Apple Calendar / iCloud**: Calendar settings → Public Calendar → Copy link
   - **Any other app**: look for "Subscribe", "iCal export" or "public ICS link"
2. In WordPress: go to **Settings → Icalviz**, paste your iCal URL and follow the 3-step wizard.
3. Copy the generated shortcode and paste it into any page or post.

= Shortcode reference =

Basic:
`[icalviz url="https://calendar.google.com/calendar/ical/…/basic.ics"]`

All options:
`[icalviz url="…" start="9" end="17" months="3" days_ahead="90" show_titles="0" disable_modal="0" legend="1" theme="light" lbl_free="Available" lbl_partial="Limited availability" lbl_full="Fully booked" cta_label="Request this slot" cta_url="https://your-booking-page.com"]`

* `url` (required) — Your public `.ics` iCal link (Google Calendar, Outlook, Apple Calendar, etc.)
* `start` (0–23, default: 8) — Start of your working day in hours
* `end` (1–24, default: 18) — End of your working day in hours
* `months` (1–12, default: 2) — Number of months to display
* `days_ahead` (0–730, default: 0) — Days ahead to show; 0 = unlimited
* `show_titles` (0 or 1, default: 0) — Show event titles in the modal timeline
* `legend` (0 or 1, default: 1) — Show colour legend below calendar
* `theme` (light / dark, default: light) — Colour theme
* `lbl_free` (text, default: Free) — Label for free days
* `lbl_partial` (text, default: Available) — Label for partially available days
* `lbl_full` (text, default: Fully booked) — Label for fully booked days
* `cta_label` (text) — Text for the call-to-action button in the modal
* `cta_url` (URL) — Link for the call-to-action button
* `disable_modal` (0 or 1, default: 0) — Disable day-click modal; show only availability colour

= Privacy =

Icalviz connects only to the iCal URL you provide. No data is sent to any third party. The iCal feed is cached locally in your WordPress database for 30 minutes. If `show_titles` is set to 0 (default), event titles are never exposed to visitors.

= Requirements =

* WordPress 5.8 or higher
* PHP 7.4 or higher
* A **public iCal URL** (`.ics` link) from Google Calendar, Outlook, Apple Calendar, Nextcloud, or any iCal-compatible service
* Your WordPress timezone must be set correctly (Settings → General → Timezone)

== Installation ==

1. Upload the `icalviz` folder to `/wp-content/plugins/`
2. Activate the plugin via **Plugins → Installed Plugins**
3. Go to **Settings → Icalviz** and follow the setup wizard
4. Copy the generated shortcode and paste it into any page or post

== Frequently Asked Questions ==

= Do I need a Google API key? =
No. Icalviz uses the standard public iCal (`.ics`) URL exposed by most calendar apps. No API key or account login is required for Google Calendar, Outlook, Apple Calendar, or any other supported service.

= My calendar says "Libre" (Free) but the modal shows nothing. =
Make sure your events are set to **"Busy"** (not "Free/Available") in Google Calendar. Events marked as "Show as: Free" are intentionally ignored by Icalviz. Also check that your WordPress timezone (Settings → General) matches the timezone of your calendar.

= Why do some days show incorrect availability? =
Run the **Debug diagnostic** in Settings → Icalviz. It shows a detailed trace of how each event is parsed and whether slots are calculated correctly. The most common cause is a timezone mismatch between WordPress and the iCal feed.

= How often does the calendar update? =
The iCal feed is cached for 30 minutes. To force an immediate refresh, click **"Flush cache"** in Settings → Icalviz.

= Can I display multiple calendars? =
Yes — place multiple shortcodes on the same page, each with a different `url` parameter.

= Can I hide event titles from visitors? =
Yes. The default is `show_titles="0"`. When disabled, the modal shows occupied time slots without any event title.

= Is it compatible with page builders? =
Yes — Elementor, Divi, Beaver Builder, and any builder that supports WordPress shortcodes.

== Screenshots ==

1. Front-end calendar — 2-month view with free, partial, and fully booked days (iCal feed from Google Calendar)
2. Admin — onboarding wizard (step 1: connect your calendar)
3. Admin — shortcode generator
4. Admin — shortcode reference

== Changelog ==

= 1.0.0 =
* Initial release
* Visual availability calendar from any public iCal feed (Google Calendar, Outlook, Apple Calendar, Nextcloud…)
* Day-click modal with 15-minute granularity timeline
* Responsive layout: 2 columns desktop / 1 mobile with navigation arrows
* Configurable working hours, booking window, and colour labels
* Call-to-action button in modal
* Dark mode theme
* Onboarding wizard with inline iCal connection tester
* Admin shortcode generator
* Debug diagnostic panel with copyable report
* GPL-2.0-or-later licence

== Upgrade Notice ==

= 1.0.0 =
Initial release.
