Add event contact email and multi-day occurrences design specifications

- Introduced a new specification for adding an optional contact email field to events, including front-end output and compatibility testing. - Added a comprehensive design document for multi-day event occurrences, detailing the new occurrence data model, validation, normalization, and calendar architecture. - Created specifications for ACF field-key switching compatibility and local ACF override compatibility to ensure seamless integration with existing themes. - Implemented a desktop calendar view toggle design, allowing users to switch between calendar and list views, with persistent preferences and responsive behavior.
2026-07-30 09:56:29 -05:00
parent 25b7a95ad5
commit 51147ef36f
49 changed files with 5333 additions and 124 deletions
@@ -0,0 +1,86 @@
+# Local ACF Override Compatibility Design
+
+## Problem
+
+AA Events suppresses its built-in ACF field group when the MNBC theme's local
+field group is enabled. The theme group stores repeating dates under
+`multiple_dates` and returns dates and times as `F j, Y` and `g:i a`. The
+plugin's occurrence reader only reads `event_dates` and strictly parses
+`Y-m-d` dates and 24-hour times. As a result, the plugin detects the local
+group as an override but cannot turn its schedule values into occurrences, so
+the events do not appear in schedule-driven views.
+
+## Scope
+
+This change makes the plugin compatible with the existing MNBC schedule fields
+and normalizes the theme's local ACF JSON to the documented AA Events schedule
+contract. It does not rename or otherwise change unrelated cost, location, or
+contact fields.
+
+## Plugin Compatibility
+
+`aa_events_get_occurrences()` will use schedule sources in this order:
+
+1. The canonical `event_dates` repeater when it contains rows.
+2. The legacy local-override `multiple_dates` repeater when it contains rows.
+3. The existing `event_datetime` fallback.
+4. The existing standalone `date` and `start_time` fallback.
+
+Canonical rows take precedence when both repeaters contain data. Legacy
+`multiple_dates` rows will normalize to the same public occurrence shape as
+canonical rows, without adding a new public source type.
+
+The occurrence parsing boundary will accept the plugin's canonical return
+formats and the formats emitted by the existing theme override:
+
+- Dates: `Y-m-d`, compact ACF `Ymd`, and `F j, Y`.
+- Times: `H:i:s`, `H:i`, and `g:i a`.
+
+All accepted values will be normalized to `Y-m-d` and `H:i:s` before existing
+range validation, sorting, and rendering logic runs. Invalid or ambiguous
+values will continue to be rejected rather than guessed.
+
+Metadata-change synchronization will recognize both repeater names and their
+schedule subfields. ACF value-cache flushing will include `multiple_dates`, so
+direct metadata changes cannot leave stale canonical occurrence indexes.
+
+## Theme ACF JSON
+
+The MNBC theme field group at
+`wp-content/themes/MNBC/acf/group_69fb58894f83f.json` will be updated as
+follows:
+
+- Rename the repeater field from `multiple_dates` to `event_dates`, retaining
+  its stable ACF field key.
+- Change the standalone and repeater Date fields' return format to `Y-m-d`.
+- Change the standalone and repeater Start Time and End Time fields' return
+  format to `H:i:s`.
+
+The existing field keys remain unchanged. No unrelated field definitions will
+be modified.
+
+## Existing Data
+
+Renaming the ACF field does not rename previously saved WordPress metadata.
+Existing rows stored as `multiple_dates_*` therefore remain in place and are
+read through the plugin compatibility fallback. Newly edited schedule data
+will be saved under canonical `event_dates_*` keys.
+
+No destructive or automatic bulk database migration is included. If both old
+and new repeater data exist on an event, canonical `event_dates` data is
+authoritative.
+
+## Testing
+
+Regression tests will first reproduce the current theme override:
+
+- `multiple_dates` rows using `F j, Y` dates and `g:i a` times produce
+  normalized occurrences.
+- Standalone legacy fields in those formats produce an occurrence.
+- Canonical `event_dates` rows win when both repeater names contain data.
+- Invalid formatted values remain excluded.
+- Metadata synchronization recognizes and flushes the legacy repeater.
+
+The focused occurrence tests and complete plugin test suite must pass after
+the implementation. The theme JSON will also be parsed to confirm it remains
+valid JSON and contains the canonical schedule names and return formats.