Season at a Glance Timeline

A WordPress Gutenberg block plugin that displays a theater season as an interactive horizontal timeline with color-coded production bars spanning performance date ranges.

Overview

Season at a Glance Timeline is designed for theater and performing arts websites. It provides a visual, interactive timeline that shows all productions in a selected season at a glance. Productions are rendered as color-coded horizontal bars spanning their performance date ranges, derived from linked GatherPress events.

Key Features

• Season Taxonomy — Registers a hierarchical "Season" taxonomy on the ft_production post type for grouping productions by season.
• Horizontal Timeline — Each production appears as a bar spanning from its first to last performance date.
• Color-Coded Bars — Productions are color-coded by any public taxonomy registered on the gatherpress_event post type (e.g., topic, venue).
• Interactive Zoom — Click any production bar to zoom into a detailed view showing individual event dates as clickable dots, the production's featured image, title, and excerpt.
• Editor Preview — Full timeline preview in the block editor with live data fetching.
• Server-Side Rendering — Frontend output is rendered via PHP for excellent SEO and performance.
• Intrinsic Design — Uses CSS Container Queries for responsive layout that adapts to any container width.
• Accessible — Full keyboard navigation, ARIA attributes, focus management, and screen reader support.
• Localizable — Respects the site's date_format, time_format, and locale settings via date_i18n().
• Themeable — Extensive CSS custom properties allow theme designers to override colors and layout dimensions.

Requirements

Requirement	Version
WordPress	6.4+
PHP	7.4+
Node.js (for development)	18+

External Dependencies

This plugin expects the following to be registered by external plugins:

Component	Expected By
ft_production post type	Theater for WordPress or similar
gatherpress_event post type	GatherPress
_ft_production_shadow taxonomy	Shadow taxonomy linking productions to events
gatherpress_topic taxonomy	Registered on gatherpress_event
_gatherpress_venue taxonomy	Registered on gatherpress_event

Tip: For testing without these plugins, use the included demo data generator.

Installation

1. Upload the plugin files to /wp-content/plugins/telex-season-timeline/.
2. Run npm install && npm run build from the plugin directory.
3. Activate the plugin through the Plugins screen in WordPress.
4. Ensure you have the required external post types and taxonomies registered.
5. Create Season terms under Productions → Seasons and assign them to your productions.
6. Add the Season at a Glance Timeline block to any post or page.

Usage

Adding the Block

1. Open the block editor on any post or page.
2. Insert the Season at a Glance Timeline block (found under the Widgets category).
3. Select a season from the dropdown in the block placeholder or the sidebar settings.

Block Settings

Setting	Description	Default
Season	Which season to display	— (required)
Color By	Taxonomy used for color-coding bars	First available event taxonomy
Order By	Sort productions by upcoming events or title	Upcoming Events
Order	Ascending or descending sort direction	Ascending
Upcoming Only	Hide past productions, clip timeline to today	Off

The Color By dropdown is automatically hidden when only one taxonomy is available — that taxonomy is used by default.

Frontend Interactions

• Hover a bar to see a tooltip with the production title, date range, and performance count.
• Click a bar or its label to zoom into the production's detail panel.
• Click outside the expanded panel or press Escape to zoom back out.
• Tab through bars for full keyboard navigation.
• Drag horizontally to scroll the timeline when it overflows.

Demo Data

The plugin includes an optional demo-data.php file that registers stub post types/taxonomies and seeds sample theater data for testing.

Seeding Data

Click 🎭 Timeline Demo → Seed Demo Data in the admin bar, or visit:

/wp-admin/?telex-seed-demo=1

This creates:

• 2 seasons (2024–2025 and 2025–2026)
• 14 productions across 5 topics and 3 venues
• Multiple GatherPress events per production with proper date ranges and shadow taxonomy links

Purging Data

Click 🎭 Timeline Demo → Purge Demo Data in the admin bar, or visit:

/wp-admin/?telex-purge-demo=1

Important: Remove demo-data.php from the plugin directory for production deployments.

Documentation

Detailed documentation for developers and theme designers is available in the /docs/ directory:

Document	Description
Architecture	Plugin structure, class design, and data flow
PHP Hooks & Filters	All available WordPress filters for customization
REST API	Custom REST endpoint reference
CSS Customization	CSS custom properties, BEM selectors, and theming guide
JavaScript API	Frontend interactivity architecture and extension points
Block Attributes	Complete attribute reference with types and defaults
Accessibility	Accessibility features and ARIA implementation
Demo Data	Demo data generator usage and configuration

Development

Setup

git clone <repository-url>
cd telex-season-timeline
npm install

Commands

Command	Description
npm start	Start development build with file watching
npm run build	Production build
npm run format	Format source files
npm run lint:js	Lint JavaScript files
npm run lint:css	Lint CSS/SCSS files
npm run plugin-zip	Create distributable ZIP
npm run test:php	Run all PHPUnit tests
npm run test:php:unit	Run unit tests only
npm run test:php:integration	Run integration tests only

Testing

The plugin includes a comprehensive PHPUnit test suite using the WordPress PHPUnit framework (wp-phpunit).

Setup

# Install WordPress test library (requires MySQL).
bash bin/install-wp-tests.sh wordpress_test root '' localhost latest

# Run all tests.
npm run test:php

# Run only unit tests.
npm run test:php:unit

# Run only integration tests.
npm run test:php:integration

Test Structure

Directory	Group	Description
tests/unit/	unit	Isolated tests for each singleton class
tests/integration/	integration	Full data flow and REST endpoint tests

Test File	Tests
class-test-color.php	Deterministic color generation, palette access, singleton
class-test-event-query.php	Shadow term resolution, event dates, individual events, term lookup
class-test-taxonomy.php	Season taxonomy registration and properties
class-test-rest-api.php	REST callback with various parameters
class-test-block.php	Block registration and locale data
class-test-orchestrator.php	Main plugin class, sub-system accessors, delegation, global functions
class-test-renderer.php	Server-side rendering, filtering, sorting, date format filters
class-test-full-flow.php	Complete flow from creation to rendering
class-test-demo-data.php	Stub registration, seed/purge functionality
class-test-rest-endpoint.php	Full REST server dispatch, route registration, parameter handling

JavaScript Tests

The plugin also includes a comprehensive JavaScript test suite covering all utility modules, hooks, and components using Jest (provided by @wordpress/scripts).

# Run all JS tests.
npm test

# Run tests in watch mode.
npm run test:js:watch

Test File	Tests
constants.test.js	Palette array, MS_PER_DAY constant
colors.test.js	Deterministic color generation, color map building
dates.test.js	Date parsing, arithmetic, locale formatting, month markers, today position
productions.test.js	Sorting, filtering, timeline range computation
useSeasons.test.js	Season fetching hook
useProductions.test.js	Production fetching hook
useEventTaxonomies.test.js	Event taxonomy discovery hook
InspectorSettings.test.js	Sidebar panel rendering and attribute updates
TimelineAxis.test.js	Month axis and today marker rendering
TimelineRow.test.js	Production row rendering with bar positioning
TimelineLegend.test.js	Color legend rendering
TimelinePreview.test.js	Full timeline preview composition
edit.test.js	Edit component integration with hooks and child components
view.test.js	Frontend IIFE initialization and DOM interaction

File Structure

telex-season-timeline/
├── telex-season-timeline.php    # Main plugin file (Singleton)
├── demo-data.php                # Demo data generator (remove in production)
├── README.md                    # This file
├── package.json                 # Node.js configuration
├── phpunit.xml.dist             # PHPUnit configuration
├── bin/
│   └── install-wp-tests.sh      # WordPress test library installer
├── tests/                       # PHPUnit test suite
│   ├── bootstrap.php            # Test bootstrapper
│   ├── class-test-base.php      # Shared test helpers
│   ├── unit/                    # Unit tests
│   └── integration/             # Integration tests
├── docs/                        # Developer & themer documentation
│   ├── architecture.md
│   ├── hooks.md
│   ├── rest-api.md
│   ├── css-customization.md
│   ├── javascript.md
│   ├── block-attributes.md
│   ├── accessibility.md
│   └── demo-data.md
├── src/                         # Source files
│   ├── block.json               # Block metadata
│   ├── index.js                 # Block registration
│   ├── edit.js                  # Editor component
│   ├── save.js                  # Save function (null for dynamic block)
│   ├── view.js                  # Frontend interactivity (plain JS)
│   ├── render.php               # Server-side render callback
│   ├── style.scss               # Shared styles (editor + frontend)
│   └── editor.scss              # Editor-only styles
└── build/                       # Compiled output (generated)

Frequently Asked Questions

What post type does this require?

The plugin expects an ft_production CPT registered by a separate plugin (e.g., Theater for WordPress). It registers the Season taxonomy on this CPT but does not create the CPT itself.

How are performance dates determined?

Dates are derived from gatherpress_event posts linked to each production via the _ft_production_shadow taxonomy. The plugin reads event start/end datetimes from GatherPress meta to calculate date ranges.

Can I customize the colors?

Colors are auto-generated based on taxonomy term labels using a deterministic hash. The same label always produces the same color. You can override the color palette by extending the Telex_Season_Timeline class or filtering the output. See the CSS Customization guide for theme-level overrides.

Does it work with Full Site Editing?

Yes. The block can be placed in any template, template part, or pattern. It uses CSS Container Queries so it adapts to whatever container width it's placed in.

Is it translatable?

Yes. All user-facing strings use WordPress i18n functions (__(), _x(), _n()). The text domain is telex-season-timeline. Date and time formatting respects the site's locale via date_i18n().

Changelog

0.1.0

• Initial release with full timeline functionality.
• Season taxonomy registration on ft_production CPT.
• Custom REST API endpoint for fetching season productions.
• Interactive zoom-in/zoom-out with expanded production panels.
• CSS Container Queries for intrinsic responsive design.
• Full keyboard navigation and ARIA accessibility.
• Localized date/time formatting with filterable format strings.
• Comprehensive CSS custom properties for theming.
• Demo data generator for testing.

License

This plugin is licensed under the GPLv2 or later.

Credits

Built with WordPress Telex for the theater community.