# BW Agenda Table — Specification

**Version:** 0.1.0 | **Last Updated:** 2026-04-28

## Purpose

A Gutenberg block that renders an event Agenda as a vertical Day View timeline. Editors drop the block onto an Agenda page, optionally filter by track or featured status, and the block reads from the host site's `session` Custom Post Type. When no Sessions exist (or the CPT isn't registered), the block falls back to demo data so the editor preview still reads correctly.

Designed to be portable across WordPress projects — no hard dependencies on a specific theme or other plugins.

## Requirements

### Functional

- **R1** — Render Sessions as a vertical timeline grouped by `start_time`, sorted chronologically across days.
- **R2** — Auto-detect single vs multi-day from data; switch to a real day picker when multi-day. Allow manual override (Auto / Single / Multi).
- **R3** — Filter by `track` taxonomy term (slug-based). Plenary/break sessions (no track) always surface alongside (OR-NOT-EXISTS rule).
- **R4** — Filter by `is_featured` flag (Featured only toggle).
- **R5** — Limit total Sessions rendered (0 = no limit).
- **R6** — Toggle visibility of: track badge, featured badge, thumbnail, description.
- **R7** — Click action: link to Session detail OR no link.
- **R8** — Demo-data fallback when no Sessions exist or CPT not registered.
- **R9** — Field-name aliases so the block works whether ACF fields are named `event_date` / `date` / `session_date`, etc.
- **R10** — Multi-day frontend interactivity: only one day section visible at a time, switched via dropdown / prev-next arrows. Progressive enhancement — JS-off shows all days stacked.

### Non-functional

- WordPress 6.0+ with PHP 7.4+
- Follows WordPress security best practices (escape on output, sanitize on input, prepared SQL via `WP_Query`)
- Translatable (i18n) via text domain `bw-agenda-table`
- Does not register the `session` CPT or `track` taxonomy — host site owns them
- Does not interfere with other plugins; CSS variables scoped under `.bw-agenda-table`

## Acceptance Criteria

| Requirement | Acceptance | Status |
|---|---|---|
| R1 | Sessions sorted chronologically; same start_time grouped under one time anchor | ✅ |
| R2 | "Auto" mode renders single label for one day, picker for two+ days | ✅ |
| R3 | Selecting a track shows that track's sessions plus untagged sessions | ✅ |
| R4 | Featured-only renders only sessions with `is_featured = 1` | ✅ |
| R5 | Limit > 0 truncates to first N rows after sort | ✅ |
| R6 | All four toggles flip the corresponding markup | ✅ |
| R7 | Click=link wraps title in `<a>`; Click=none uses `<span>` | ✅ |
| R8 | With no `session` CPT, demo rows render and an admin-only note shows | ✅ |
| R9 | All listed field aliases tested with ACF and plain post meta | ✅ |
| R10 | view.js initialises only when 2+ day sections present | ✅ |