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,133 @@
+# Event Contact Email Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add an optional event contact email field and display valid values as protected email links on single-event pages.
+
+**Architecture:** Register `event_contact_email` in the built-in ACF group and read the same field name from built-in or admin-created groups. Keep output in the single-event template, sanitizing before conditional rendering and applying WordPress escaping at the attribute and visible-HTML boundaries.
+
+**Tech Stack:** PHP 7.4+, WordPress template APIs, ACF PRO, existing dependency-free PHP tests
+
+---
+
+### Task 1: Register the Contact Email Field
+
+**Files:**
+- Modify: `includes/acf-fields.php`
+- Modify: `tests/bootstrap.php`
+- Modify: `tests/test-acf-fields.php`
+
+- [ ] **Step 1: Write the failing registration test**
+
+Extend the ACF test double to capture `acf_add_local_field_group()` arguments. In `tests/test-acf-fields.php`, clear admin groups, call `events_register_acf_fields()`, locate the field named `event_contact_email`, and assert this exact contract:
+
+```php
+array(
+	'key'      => 'field_aa_events_contact_email',
+	'label'    => 'Contact Email',
+	'name'     => 'event_contact_email',
+	'type'     => 'email',
+	'required' => 0,
+)
+```
+
+- [ ] **Step 2: Run the suite and verify RED**
+
+Run: `php tests/run.php`
+
+Expected: FAIL because no field named `event_contact_email` is registered.
+
+- [ ] **Step 3: Add the built-in field**
+
+Add the optional ACF email field after location/URL/address details in `includes/acf-fields.php`, using the stable key and contract above plus standard empty wrapper/default/placeholder settings.
+
+- [ ] **Step 4: Verify GREEN**
+
+Run:
+
+```bash
+php tests/run.php
+php -l includes/acf-fields.php
+```
+
+Expected: all tests pass and syntax is valid.
+
+### Task 2: Render Contact Email on Single Events
+
+**Files:**
+- Modify: `templates/single-event.php`
+- Modify: `tests/bootstrap.php`
+- Create: `tests/test-contact-email.php`
+- Modify: `tests/run.php`
+
+- [ ] **Step 1: Write failing output tests**
+
+Add minimal `sanitize_email()` and `antispambot()` doubles if absent. Test a focused helper named `aa_events_contact_email_markup()` with:
+
+```php
+aa_events_assert_same( '', aa_events_contact_email_markup( '' ), 'Empty email renders nothing.' );
+aa_events_assert_same( '', aa_events_contact_email_markup( 'not an email' ), 'Invalid email renders nothing.' );
+$markup = aa_events_contact_email_markup( 'events@example.com' );
+aa_events_assert_true( false !== strpos( $markup, 'mailto:' ), 'Valid email has a mailto link.' );
+aa_events_assert_true( false !== strpos( $markup, 'events@example.com' ), 'Valid email remains readable.' );
+```
+
+Also assert `templates/single-event.php` reads `event_contact_email`, calls the helper, and renders the `Contact Email:` label only when markup is non-empty.
+
+- [ ] **Step 2: Run the suite and verify RED**
+
+Run: `php tests/run.php`
+
+Expected: FAIL because `aa_events_contact_email_markup()` does not exist.
+
+- [ ] **Step 3: Implement safe markup and template output**
+
+Add this focused template helper to `includes/template-loader.php`:
+
+```php
+function aa_events_contact_email_markup( $value ) {
+	$email = sanitize_email( (string) $value );
+	if ( '' === $email || $email !== trim( (string) $value ) ) {
+		return '';
+	}
+	$protected = antispambot( $email );
+	return '<a href="' . esc_attr( 'mailto:' . $protected ) . '">' . wp_kses_post( $protected ) . '</a>';
+}
+```
+
+In `templates/single-event.php`, call the helper with `get_field( 'event_contact_email' )`. When non-empty, render an `.aa-event-contact-email` detail row with localized label `Contact Email:` and output only the helper's already constrained anchor through `wp_kses_post()`.
+
+- [ ] **Step 4: Run complete verification**
+
+Run:
+
+```bash
+php tests/run.php
+php -l includes/template-loader.php
+php -l templates/single-event.php
+phpcs --standard=WordPress includes/acf-fields.php includes/template-loader.php templates/single-event.php
+```
+
+Expected: tests and syntax pass. Record unrelated pre-existing PHPCS findings separately rather than changing unrelated template code.
+
+### Task 3: Documentation and Final Check
+
+**Files:**
+- Modify: `README.md`
+
+- [ ] **Step 1: Document the optional field**
+
+Add Contact Email to the Event Details list and state that it appears only on single-event pages when valid.
+
+- [ ] **Step 2: Run final verification**
+
+Run:
+
+```bash
+php tests/run.php
+find . -path './.superpowers' -prune -o -name '*.php' -print0 | xargs -0 -n1 php -l
+```
+
+Expected: all tests and PHP syntax checks pass.
+
+The workspace is not a Git repository, so commit steps are unavailable.