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,62 @@
+# ACF Field-Key Switching Compatibility Design
+
+## Problem
+
+The built-in and theme-local field groups use different ACF field keys. Event
+415 currently has canonical `event_dates` metadata whose hidden reference
+points to the built-in repeater key, while the active database copy of the
+theme group still defines its repeater as `multiple_dates`. ACF cannot resolve
+the inactive key through `get_field()`, so normal field loading can return only
+the raw repeater count instead of its rows. The front end remains visible
+because AA Events falls back to the standalone `date` field.
+
+The updated theme JSON has not yet been synchronized into ACF's database field
+definitions.
+
+## Field-Group Synchronization
+
+Import the existing theme JSON group through ACF's field-group import API. The
+import retains every stable theme field key while updating the database copy
+to use the canonical `event_dates`, `Y-m-d`, and `H:i:s` contract.
+
+The import is a one-time site synchronization, not an automatic plugin
+mutation of arbitrary external ACF groups.
+
+## Runtime Field Loading
+
+AA Events will resolve a supported field through the currently registered ACF
+field definition when one is available, rather than relying only on the hidden
+metadata reference. This lets `event_dates` load through whichever field key
+is active:
+
+- Built-in: `field_61b0c7f0a3e8f`.
+- MNBC local group: `field_69fb5b1aac54a`.
+
+The existing `get_field()` path remains the fallback for tests, legacy fields,
+and installations where the lower-level ACF APIs are unavailable.
+
+## Legacy Repeater Migration
+
+Add an idempotent migration helper for event posts:
+
+1. Do nothing when canonical `event_dates` contains rows.
+2. Read and normalize legacy `multiple_dates` rows.
+3. Write equivalent canonical rows to the currently registered
+   `event_dates` field.
+4. Preserve the legacy metadata rather than deleting it.
+
+Run this migration once for the live MNBC events after synchronizing the field
+group. Keep the helper available on event saves so a legacy-only event becomes
+canonical when edited.
+
+Canonical rows remain authoritative if both formats exist.
+
+## Verification
+
+- Add regression tests for loading a canonical repeater through an active ACF
+  definition even when its hidden reference belongs to the inactive group.
+- Add idempotent migration tests for legacy-only and already-canonical events.
+- Run the complete plugin test suite and PHP syntax checks.
+- Confirm the live ACF database field definition is named `event_dates`.
+- Confirm event 415 returns an occurrence from `event_dates`.
+- Inspect the raw metadata and verify no legacy schedule metadata was deleted.