PRC Chart Builder

Version 3.14.0

A WordPress plugin for building, managing, and embedding interactive SVG charts on the Pew Research Center platform. Charts are authored as a custom post type (chart) using the Gutenberg block editor and rendered via the PRC Charting Library (prc-charting-library), which is built on @visx and D3.

Breaking change — Chart Builder 3.0: The plugin's block namespace was updated to follow the {plugin-name}/{block-name} convention. References should use prc-chart-builder/chart, prc-chart-builder/controller, and prc-chart-builder/synced-chart. The npm package is @prc/chart-builder. A WP-CLI command is included to aid bulk migration of legacy data.

---

Overview

How charts are built

1. Open Charts in wp-admin (the Chart Library is All Charts — wp-admin/edit.php?post_type=chart)
2. Add New Chart opens a new chart post. When the site-level creation UI is on, the CPT wizard runs Pattern → Data → Configure → Preview. When it is off, the classic type picker still appears.
3. The chart opens in the block editor as a prc-chart-builder/controller block containing a prc-chart-builder/chart inner block
4. Paste or type CSV data into the data table; the chart renders live in the editor
5. Use the sidebar panels and the click-to-style element popover (click any bar, label, line, or map region) for fine-grained customization
6. Publish — the chart is now available to embed in articles via the prc-chart-builder/synced-chart block

Block structure

prc-chart-builder/controller   (outer — data table, context, freeform chart hosting)
  └── prc-chart-builder/chart  (inner — all chart config stored here as attributes)
  └── core/table               (optional — canonical CSV data source)

When embedding a chart into an article, editors use prc-chart-builder/synced-chart, which holds a reference (ref) to the chart CPT post and delegates rendering to the controller block inside it.

Key systems introduced in 3.5.0

System	What it does
Chart Library admin	DataViews-based gallery with filtering, previews, and multi-path creation
AI generation	Text + image + CSV → complete chart block, with live preview before accepting
Element popover	Click any chart element in the editor to open a per-element style panel
Dark mode	Charts automatically respond to OS/browser color scheme via CSS light-dark()
Sankey chart	New chart type for flow/allocation data
Treemap chart	New chart type for hierarchical part-to-whole data
Scatter grouping	Color-code scatter points by a secondary variable; legend reflects groups
Regression lines	Overlay linear/exponential/polynomial/log/power/quadratic fits on scatter plots
Map improvements	US block map responsive scaling, missing world map territories, per-region popover

See [docs/release-notes/3_5_0.md](../../docs/plugins/prc-chart-builder/release-notes/3_5_0.md) for the full release notes.

Key systems introduced in 3.14.0

System	What it does
Chart Creation wizard	Pattern → Data → Configure → Preview on the chart CPT (site-level rollout toggle)
Chart Theme	Site-owned chart-theme.json defaults and palettes, with scoped frontend delivery
Small Multiples (BETA)	One panel per series or group with shared scales
Waffle / Beeswarm / Heat Map Table	New chart types for grid, distribution, and demographic × category encodings
Color swatch picker	Combine palettes, click swatches, drag to set series order
Tooltip templates	RichText token templates, unified hover, and minDisplayValue floors

See [docs/release-notes/3_14_0.md](../../docs/plugins/prc-chart-builder/release-notes/3_14_0.md) for the full 3.14.0 release notes.

---

Usage

Charts are managed through the Chart Library admin page (wp-admin/edit.php?post_type=chart). The chart editor is the standard Gutenberg block editor.

Embedding a chart in an article:

Use the prc-chart-builder/synced-chart block and select the chart post to embed. This creates a live reference — updates to the chart post are reflected everywhere it is embedded.

Viewport-responsive customization:

All chart attributes support per-viewport overrides via the mobile and tablet top-level attribute groups. Switch the editor to Tablet or Mobile preview to apply breakpoint-specific values. See viewport usage guide.

Per-element styling:

Click any bar, label, line segment, pie slice, map region, axis tick label, or legend item in the editor canvas to open the element popover. Changes update live and are stored in per-element attribute maps (labels.customLabels, shapes.customStyles, customTickLabels, customLegendLabels, and others) keyed by {x}::{category} or category name.

Row filtering (Data tab):

Exclude table rows from the plot without deleting CSV data. Set dataRender.rowFilter.exclude to first-column values (the inspector always writes rowFilter.column as "x"). Filtered rows stay in the data table; only the chart omits them.

---

Development

# Build (cache-aware; also builds upstream @prc/* dependencies first)
npx turbo build --filter=@prc/chart-builder

# Watch
npm run start -w @prc/chart-builder

# Build the charting library on its own
npx turbo build --filter=@prc/charting-library

The plugin depends on @prc/charting-library and @prc/charting-utilities. Changes to those packages require a rebuild before they are reflected in the chart editor or frontend — Turbo's ^build dependency handles this for you when you build @prc/chart-builder. Avoid npm run build -w @prc/chart-builder, which bypasses both the local and remote Turbo cache.

PHP: Requires PHP 8.1+. Key classes are in src/chart/class-chart.php and src/controller/class-controller.php.

Tests:

# JavaScript unit tests (theme + chart utils)
npm test -w @prc/chart-builder

# PHP unit tests (requires wp-phpunit bootstrap)
composer test -d plugins/prc-chart-builder

---

Chart Theme (PRC-528)

Each site stores one active chart theme in the prc_chart_builder_theme option:

{
    "config": { "...": "per-role defaults for newly inserted charts" },
    "palettes": { "colors": { "general": ["#…"], "brand-blue": ["#…"] } }
}

Admin UI: Charts > Chart Theme (manage_options — administrators only).

Tab	What it edits	Retroactive?
Chart Settings	theme.config defaults (layout, axes, legend, fonts, …)	No — new charts only
Color Settings	theme.palettes (palette designer)	Yes — charts referencing a palette by io.colorValue slug re-skin at render

Runtime delivery: window.prcChartBuilderTheme is attached via wp_add_inline_script only when a chart-builder bundle is enqueued (frontend chart render, block editor, Chart Library admin). Palettes resolve by slug via getResolvedPalettes(); per-role fontFamily preset tokens (var:preset\|font-family\|<slug>) resolve to concrete stacks via window.prcChartBuilderTheme.fontFamilies.

WP-CLI:

wp prc-chart-builder seed-theme          # seed fallback theme from chart-theme.json
wp prc-chart-builder repair-theme        # validate + re-seed if corrupt
wp prc-chart-builder font-tokens-audit   # audit literal font stacks in chart blocks
wp prc-chart-builder font-tokens-migrate --dry-run
wp prc-chart-builder font-tokens-migrate --batch-size=100 --sleep=1

Import / export: On Charts → Chart Theme, use Download JSON to export the in-editor draft as chart-theme.json, or Upload JSON to replace the draft from a file (then Save). Uploads are validated against the editor field registry (unknown keys, bad types/enums, and invalid palette swatches are rejected). The committed includes/settings/chart-theme.json is only the empty-site / repair fallback seed — it is not synced from the DB. It is typed via $schema pointing at the generated schema on pewresearch/prc-chart-builder trunk (built from src/settings/field-registry/schema.mjs by npm run sync:field-registry); CI fails if the seed drifts from the editor schema.

Distributor: Chart blocks keep palette slugs in io.colorValue; the destination site resolves colors from its own theme.palettes — the theme option is not distributed.

---

Documentation

Document	Description
docs landing page	Plugin docs hub (editors + maintainers)
user guide	Editorial workflow and chart creation
architecture	System architecture, data flow, state management
REST API	Custom prc-chart-builder/v1 routes
Abilities	prc-chart-builder/generate AI ability
viewport attributes	Viewport-aware attribute system internals
viewport usage guide	Practical guide to responsive chart customization
viewport breakpoints	Breakpoint values, detection logic, and fallback behavior
reactive store	The prc-chart-builder/chart interactivity store and its actions
console helpers	window.prcChartBuilder.* devtools handles
release notes	Per-version release notes (3.5.0 → 3.14.0)
element popover README	Element popover system internals and extension guide

---

Configuration Reference

All chart configuration is stored as a single chart block attribute object on the prc-chart-builder/chart inner block. The tables below document every sub-attribute, its parent group, accepted type, default value (sourced from block.json and baseConfig.ts), and a short description.

Note: Defaults shown here reflect the block.json defaults. baseConfig.ts (used at runtime in the charting library) may carry different defaults for some fields; any significant divergence is noted.

---