=== Coyomi – Archive Calendar ===
Contributors: piftoworks
Tags: calendar, archives, widget, performance
Requires at least: 5.5
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.3.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

An archive calendar widget that adds no database queries to your pages.

== Description ==

Many archive calendar widgets query the database for every month on every page view.
On a site with years of posts that means around a hundred queries per page.

This widget aggregates the days that have posts once, when content changes, and writes them
to a static JSON file under `wp-content/uploads/lwac/`. Page views only read that file.

Coyomi (暦) means "calendar" in Japanese.

* One query per rebuild (`SELECT DISTINCT DATE(post_date)`), none per page view
* Rebuilt when a post is published, unpublished, trashed, deleted, re-dated or re-categorized, plus once a day
* The first month is rendered in HTML (works without JavaScript); other months are drawn in the browser
* Works with full-page caches: the browser always fetches the current data file
* Filter by post types and categories
* Five layouts: month calendar, week strip, year (12 month tiles), dropdowns only, and a year / month / day tree
* A settings page (Settings → Coyomi) with a live preview. Widgets follow it unless they choose their own layout and colors
* Five color schemes (Calendrier, Pastel, Classic, Dark, Simple). Every color can be changed per widget; only the changed colors are saved
* Other plugins can add events (e.g. sales) to days with the `coyomi_events` filter. An event held on several days in a row is listed on one line, marked "On now" or "Ended"
* No external requests: the calendar talks to no service outside your site and collects no data

== Developers ==

Add events with the `coyomi_events` filter. It is called only when the data is rebuilt (never on page views),
so it may do slow work. Add one entry per day:

    add_filter( 'coyomi_events', function ( $events, $dataset ) {
        try {
            foreach ( my_plugin_sale_days() as $day ) {
                $events[] = array(
                    'date'   => $day,                    // 'YYYY-MM-DD' in the site's time zone
                    'label'  => 'Autumn sale',           // plain text, up to 60 characters
                    'url'    => get_permalink( 123 ),    // a post on this site, or ''
                    'color'  => '#bf0000',               // '#rrggbb' or '#rgb', or '' for the scheme's color
                    'source' => 'my-plugin',             // a-z, 0-9, _ and -, up to 32 characters
                );
            }
        } catch ( \Throwable $e ) {
            // Rebuilds also run on a reader's first page view and in cron. On failure, add nothing.
        }
        return $events;
    }, 10, 2 );

How events are shown:

* Days in a row with the same `label`, `url` and `source` are listed as one line (e.g. "12/4–12/11").
  Keep these three the same on every day of one event.
* Entries with the same `date`, `label` and `url` are shown once, even when two plugins add them.
* The list marks events held today as "On now" and past events as "Ended", using the reader's date in the browser
  (so a cached page still shows the right state).
* Events do not change the month the calendar opens on. Readers reach them with the previous / next buttons.
* Entries with a date that does not exist or an empty label are dropped.

Rules for plugins that add events:

* Add only the events your plugin owns. Do not pass on events your plugin received from another plugin;
  that plugin can add them itself.
* `url` must be a post or page on this site. Event links have no `rel` attribute, so never use affiliate
  or other paid links there.
* `date` is a date in the site's time zone (Settings → General). The data is rebuilt when the time zone,
  the permalink structure or the site address changes.

When your events change, ask for a rebuild. It runs once at the end of the request:

    do_action( 'coyomi_request_rebuild' );

When your plugin is deactivated, remove your filter before asking for the rebuild, so that the rebuild at
the end of the same request does not add your events back.

The data file URL is built from the site URL (not the uploads URL), so it keeps working when media is
served from another domain or a CDN. If your setup still needs a different URL:

    add_filter( 'coyomi_data_url', function ( $url, $key, $path ) {
        return $url; // must be readable from the page (same origin, or CORS allowed)
    }, 10, 3 );

== WP-CLI ==

* `wp coyomi status` - data files and last rebuild
* `wp coyomi rebuild` - rebuild all data files
* `wp coyomi compare lwac_calendar-2` - run the legacy per-month queries once and compare the days

== Changelog ==

= 0.3.0 =
* Events held on several days in a row are listed on one line (e.g. "12/4–12/11"), including days outside the month shown.
* The event list marks events as "On now" or "Ended". The state follows the reader's date, so cached pages stay correct.
* Identical events (same date, label and URL) are shown once, even when two plugins add them.
* Events no longer change the month or week the calendar opens on. It opens on the latest month with posts.
* In the week layout, choosing a month in the menu opens the week of the latest post in that month.
* A year tile shows one mark per event instead of one per day.
* The data is rebuilt when the permalink structure, the site address or the time zone changes.
* If a plugin that adds events fails while the data is rebuilt, the calendar keeps the days with posts.
* Translations are delivered as language packs from translate.wordpress.org.

= 0.2.1 =
* Fixed: with classic widgets, changing a calendar in the Customizer showed "An error has occurred" and the Publish button stayed disabled.
* Fixed: in the week layout, the month name on the first day overlapped the weekday.

= 0.2.0 =
* Renamed to Coyomi. Settings, widgets and data of earlier versions are kept as they are.
* Hooks and WP-CLI use the new name: coyomi_events, coyomi_request_rebuild, coyomi_data_url, wp coyomi.

= 0.1.4 =
* Removed the migration from Archives Calendar Widget (the settings page panel and its WP-CLI command). Calendars created with it keep working as they are.

= 0.1.3 =
* Color fields show the current color instead of a blank swatch, and the color picker opens at that color.
* The help text refers to the "Default" button, matching the button label.

= 0.1.2 =
* Fixed: the Simple color scheme showed no grid lines or frame.
* Fixed: in the year layout, the current month tile could lose its text. Simple now marks today in red even on days with posts.
* "Edit in the Customizer" opens the area where each calendar is placed.
* The colors panel on the settings page is always open.

= 0.1.1 =
* Settings page (Settings → Coyomi) with a live preview, placement list, legacy migration and data status.
* Widgets follow the site-wide layout, colors and nofollow unless set per widget.
* The data file URL is built from the site URL, so it works when uploads are served from another domain.
* Fixed: layout and color scheme buttons overlapped on the settings page.
* CSS and JS URLs change whenever the files change, so CDNs do not keep serving old copies.

= 0.1.0 =
* First version.
