Guide

Chart Builder 3.14.0 — Release Notes

Release: Chart Builder 3.14.0 · PRC Platform 1.13 Work period: June – August 2026 Scope: prc-chart-builder, prc-charting-library, prc-charting-utilities, prc-block-tables, prc-scripts Tracking: PRC-626 · PR #4380

Overview

Chart Builder 3.14.0 is a large authoring-and-expressiveness release. These initiatives ship together:

  1. Chart Creation wizard (PRC-527, PRC-684) — a guided Pattern → Data → Configure → Preview flow on the chart CPT editor, with curated controls, live preview, viewport toggles, design mode, and a second UX pass that unblocks template pick and routes synced-chart create into a new tab.
  2. Chart Library as All Charts — the DataViews Chart Library becomes the primary Charts admin destination, with static PNG thumbnails, list/grid/table layouts, classic-list escape hatch, and Trashed filtering. Add New Chart opens a new chart post (post-new.php) rather than an inline library wizard.
  3. Chart Theme system (PRC-528 / PRC-560 / PRC-628) — site-level chart-theme.json defaults and palettes, admin import/export bound to the field registry, and scoped theme delivery so pages without charts no longer pay the inline theme payload.
  4. Small Multiples (BETA) (PRC-637) — one panel per series or group with shared scales, restack-safe drawings/annotations, and area/node rendering that stays locked through resize.
  5. New chart types — Waffle, Beeswarm (PRC-52), and Heat Map Table (PRC-268).
  6. Scatter variable dot sizing (PRC-433) — size dots from a numeric column (same square-root approach as bubble maps), with shared scale types across scatter and beeswarm.
  7. Multi-palette color swatch picker (PRC-710) — combine palettes, click swatches into the chart, and drag to set series order, with legend labels beside each chip.
  8. Tooltip authoring — RichText token templates (PRC-709), unified hover for line-family charts, and a minDisplayValue floor so small values read as <0.1 instead of rounding to zero.
  9. Axis / label / map / legend / runtime polish — nice-domain toggle with v1.12 parity (PRC-541), mirrored negative bar label DX (PRC-437), map requirements on the Power Table (PRC-530), detached-legend paragraph alignment (PRC-485), first/last line labels and nodes, grouped bar thickness, negative bar baseline, sibling duplicate Chart ID modal, and assorted editor/font/runtime fixes.

What's New

1. Chart Creation wizard (PRC-527, PRC-684)

Background

The Chart Library create modal previously stopped at type/pattern selection (or AI prompt) and dumped the editor into a blank chart post. Authors still had to wire data, sanity-check the render, and hunt through the full inspector before knowing whether the chart was viable. PRC-527 turns creation into a complete guided flow so a chart can leave the authoring session already configured. PRC-684 is the follow-up UX pass after that first ship.

What shipped

Guided multi-step flow (hosted on the chart CPT)

When the site-level creation UI is enabled, new chart posts open into ChartCptWizardShell inside the controller editor:

  1. Pattern

    Pick a chart type, variation, or pattern template.

  2. Data

    Edit the embedded power table. Set column types from the cell context menu, or drop a CSV.

  3. Configure

    Use curated controls and a live preview. Optional design mode opens the full canvas and inspector.

  4. Preview

    Check the interactive canvas with viewport and color-mode chrome before publishing.

Chart Library Add New Chart navigates to post-new.php?post_type=chart rather than hosting the wizard inline on the library page. The compact modal ChartWizard remains for the classic controller placeholder when the new creation UI is off.

Data flows table → chart through pure helpers (tableAttributesToChartData, seedChartAttributes, refreshPreviewData, deriveChartAttributesOnNext, buildPreviewChartData) so curated edits survive Back / Next.

Preview viewport controls

Configure / Preview resolve a definite card width per viewport:

  • Desktop — chart at its authored layout.width; the pane scrolls if needed
  • Tablet / Mobile — constrained as those viewports would on the frontend
  • Custom width slider — covers widths between the named breakpoints (where label declutter and legend wrapping change) up to the chart's own layout.width

Site-level rollout toggle

Charts → Settings (creation UI) keeps the classic variation picker enabled by default. Administrators can flip the site onto the new wizard without a code deploy. See includes/settings/class-creation-ui-settings.php.

Pass 2 UX (PRC-684, PR #4441)

  • Pattern step no longer stalls on template pick — Continue to Add Data advances to Data / Configure
  • Template previews are lazy and capped to cut server load
  • Synced-chart Create New Chart opens the chart post editor in a new tab instead of the compact modal
  • Configure step shows data-derived placeholders when axis domains are auto
  • Line-family charts restore auto min/max when axes are unset, without treating legacy { min, max } or sentinel domains like [2000, 2020] as hard bounds
  • Line templates default showPoints on; node stroke defaults to series color (legacy white inherits; the White preset is removed in favor of Custom)

Dev helpers

configurePreviewDebug console helpers remain available for browser smoke testing during development.

2. Chart Library as All Charts

The DataViews Chart Library screen is now the destination for Charts → All Charts. Unused Charts submenu items are hidden from the menu while remaining reachable by URL. Authors who need the classic list table get an escape hatch, and Trashed status filtering lands in the DataViews UI.

Gallery performance (PRC-268)

  • Static PNG thumbnails for chart cards (via Chart_Static_Images) instead of live block previews in the gallery
  • Pruned REST payload and client-side page caching for faster All Charts loads
  • Cached chart-patterns library endpoint for the creation wizard's Pattern step
  • Template previews aligned with site-editor BlockPreview settings and styling

Layouts

The gallery supports list, table, and grid layouts alongside the existing DataViews chrome.

3. Chart Theme system (PRC-528 / PRC-560 / PRC-628)

Background

Chart Builder baked Pew-centric defaults (fonts, padding, axis chrome, hardcoded palettes) into baseConfig / colors.js. Opening the project for external use — and letting other PRC properties diverge — required moving those defaults into a site-owned theme that administrators can edit without a deploy.

What shipped

Site theme option

Each site stores one active chart theme in prc_chart_builder_theme:

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

Admin UI — Charts → Chart Theme (manage_options)

TabEditsRetroactive?
Chart Settingstheme.config defaults (layout, axes, legend, fonts, …)No — new charts only
Color Settingstheme.palettes (palette designer)Yes — charts referencing a palette by io.colorValue slug re-skin at render

Import / export (PRC-560)

  • Seed file renamed to includes/settings/chart-theme.json (empty-site / repair fallback only — not synced from the DB)
  • Download JSON / Upload JSON on the Chart Theme screen
  • Uploads validated against the editor field registry; unknown keys, bad types/enums, and invalid palette swatches are rejected
  • Generated chart-theme.schema.json for IDE typing; CI fails if the seed drifts from src/settings/field-registry

Scoped delivery (PRC-628)

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). Pages without charts no longer pay ~11 KB of inline theme JSON. The palette repair path is hardened with a once-per-request guard.

WP-CLI

wp prc chart-builder seed-theme
wp prc chart-builder repair-theme
wp prc chart-builder font-tokens-audit
wp prc chart-builder font-tokens-migrate --dry-run

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

See the Chart Theme section in the plugin README.

4. Small Multiples (BETA) (PRC-637)

Background

Producers regularly need side-by-side panels of the same encoding (one series / group per panel) with shared scales — previously approximated with Freeform nesting or hand-rolled layouts. PRC-637 adds a first-class small-multiples chart type.

What shipped

  • Faceting — by series column or by group (groupBreaksCategory)
  • Panel types — line, column, bar, pie (waffle portion mode also participates when used as a panel type)
  • Shared scales — computeSharedDomain keeps axes aligned across panels
  • Responsive grid — computePanelRects restacks on resize; viewport column overrides supported; locked panelHeight with SVG height derived from row count
  • Marks & chrome — labels, tooltips, customStyles, line segmentStyles, plot bands, highlight / ghost (line), shared pie legend
  • Drawings & annotations — positioningContext: 'panel' + panelKey; restack-safe panel buckets; editor annotation Panel picker when layout.type === 'small-multiples'
  • Inspector — Small Multiples panel; Line / Bar / Pie controls gated by panelType

5. Waffle charts

New Waffle variation with pie-like category encoding on a fixed cell-scale grid.

ControlBehavior
Display modewhole (single waffle) or portion (works with small-multiples panels)
GridFixed columns / rows via cell scale
CategoriesSame category model as pie
Domain maxFill semantics relative to an explicit domain max

Chart Builder ships dedicated waffle-controls.jsx inspector UI and variation icon art.

6. Beeswarm charts (PRC-52)

New Beeswarm chart type with two layout modes:

ModeBehavior
Dodge (precise)Keeps approximate x positions with configurable spread
Force (clustered)Clusters dots organically; supports group-by centers

Data convention matches every other chart type: first column is the label dimension (dataRender.x); the plotted value comes from a category column. (An earlier template put the numeric value first, which collided element keys and left {{row}} empty — corrected for ship.)

Shared with scatter

  • Variable node sizing via createPointRadiusScale (sqrt | linear | log, plus minValue floor for log domains)
  • nodes.sizeColumn folded into nodes.sizeCategory
  • Per-point custom shape colors apply even when groupBreaksCategory drives series color
  • Tooltips honor custom per-point headers; {{row}} resolves to the row label

Beeswarm is wired into curated theme config groups so Chart Theme defaults apply. AI chart-generation prompts were updated for the label/value column split.

7. Heat Map Table (PRC-268)

New Heat Map Table chart type for demographic × category grids — the Pew-style heat tables producers previously approximated with other layouts.

CapabilityBehavior
Cell colorValue-scaled fills via dataRender.mapScale — linear, threshold, or ordinal
LabelsOptional in-cell values with contrast-aware fill
ChromeRow labels, column headers, cell gap / radius, empty-cell fill, min cell width / height
Group BygroupBreaks* partitions rows into sections with italic section headers and gaps
LegendLinear / threshold / ordinal legends reused from the map stack
TooltipsShared tooltip formatting / custom headers

Layout helpers live in @prc/charting-utilities (computeHeatMapTableLayout, computeHeatMapTableCells, createValueColorScale). Chart Builder ships heat-map-table-controls.jsx, variation template + icon art, and theme-registry wiring so Chart Theme defaults apply.

8. Scatter variable dot sizing (PRC-433)

Scatter plots can size dots from a numeric data column using square-root scaling (same approach as bubble maps). Scale-type control (sqrt / linear / log) ships on scatter as well, backed by the shared radius-scale helper used by beeswarm.

9. Multi-palette color swatch picker (PRC-710)

Style Chart → Appearance replaces the single palette dropdown with an Illustrator-style swatch picker.

StepWhat authors do
Palette sourcesMulti-select named palettes from the site theme. Selected slugs feed the swatch pool.
Swatch gridDense squares grouped by palette. Click a swatch to add or remove it from the chart's series colors.
ArrangeExisting color sorter operates on the picked subset. Legend labels (including map threshold bins) sit beside each chip.

Charts saved before multi-palette sources existed still show their io.colorValue palette unforced — opening the picker does not freeze theme-linked colors until the author toggles a swatch. Clearing every palette token stays empty instead of reseeding the last source.

Picked hexes live in io.customColors (unchanged render path). io.colorPaletteSources records which palettes feed the grid.

10. Tooltip authoring

RichText tooltip template (PRC-709)

Authors compose hover text with bold/italic and insert tokens for the hovered point ({{row}}, {{value}}, {{column}}) plus any data-column key from the flat row. Templates take precedence over the legacy mustache format string, which remains the fallback for existing charts. Legacy modifiers (.isColor(), .isBold(), .toLowerCase()) continue to work in templates. Absolute-value formatting applies to numeric row-field tokens.

Inspector gate:

  1. tooltip.template is set → RichText Tooltip Template control
  2. template is null and format is customized → legacy Tooltip Format TextControl
  3. Otherwise → Template control; first edit writes template and leaves format alone

Per-point custom tooltips still win over both. Hovering a diverging-bar neutral segment now surfaces that bar's own value.

Unified tooltip mode

tooltip.mode is point (default) or unified. Unified reports every series plotted at the hovered x — hover anywhere in a year's column and read the whole cluster. Line, scatter, and stacked-area mouse hover pass the full data row, so data-column tokens work on the primary hover path.

Display floor (minDisplayValue)

Values below an author-set floor render as <value (for example <0.1 or <10K) instead of rounding to zero. The floor is a number-formatting option on both labels and tooltips. It is unrelated to labels.labelCutoff, which decides whether a label is drawn at all.

First / last line labels

labels.firstLastLabelLayout on line-family charts: outside puts the first label left of its point and the last label right. labelPositionDX / DY still apply on top.

First / last line nodes (PRC-660)

Line, area, stacked-area, and small-multiples line panels can show circular markers on only the first and last plotted point in each series. The control lives under Line Nodes and stays off unless nodes are on. Existing charts keep all-node markers until an author opts in (line.showFirstLastPointsOnly, default false).

11. Axis, label, map data, legend, and runtime polish

Nice domain toggle (PRC-541)

Authors can turn Visx/d3 nice-domain rounding on or off. dependentAxis.nice defaults to true so existing charts keep v1.12 tick rounding (an explicit [0, 76] domain still paints as [0, 80]). When nice is unset, rounding is off for an explicit domain and on for a data-derived domain. Time scales only honor Date or ISO date-string domains; bare numeric pairs persisted by legacy charts stay inferred from the data extent.

Mirrored negative bar label DX (PRC-437)

On diverging bar charts, labelPositionDX is mirrored for negative bars so a single DX value keeps positive and negative labels symmetrical.

Grouped bar thickness (PRC-640)

When grouping is on, a one-item group no longer draws a shorter bar than a larger group. Stacked, diverging, exploded, and clustered bar charts share the same group band-scale padding so thickness stays even.

Negative bar baseline (PRC-553)

The Bar chart type grows from zero when the dependent axis minimum is below zero. Positive bars no longer stretch to the new min. Line area fills (including small-multiples line panels) use the same zero baseline, so the fill meets zero from both sides. A solid axis-colored line marks zero when the domain crosses it on bar, line, stacked area, and scatter charts, matching diverging bars. Stacked, exploded, and diverging bar charts already baselined from zero and are unchanged.

Map data requirements on the Power Table (PRC-530)

FIPS / ISO / CBSA column guidance and sample CSV links move off the chart controller inspector onto the Power Table Table data import/export panel — where producers actually load data. Selecting a map chart type auto-applies the matching validation schema to the sibling table. The table validator:

  • Recognises renderer header names (ISO, FIPS, CBSA / GEOID)
  • Flags misnamed columns (e.g. ISO Code instead of ISO)
  • Validates untagged geo column cell values when only the header matched
  • Adds a geo-cbsa schema for metro maps

Tables persist a derived validationMessage summary alongside isValid. Chart editor notices name the failing required field (e.g. "Required field: ISO"). Chart post editor sessions default to the Top toolbar preference on first load.

Detached legend paragraph styling (PRC-485)

Detached legend items gain a Paragraph group in the element popover: text align (left / center / right), line height, and letter spacing. Alignment applies per legend item so a detached stack can mix alignments.

Duplicate chart IDs

When sibling controllers in the same editor share a Chart ID, editors get a modal with Regenerate ID / Keep ID. Render-time dedupe remains the safety net.

Synced-chart usage tracking

Usage tracking moves off the frontend render path onto the post-publish pipeline (publish / update / untrash), with legacy reverse-index recovery, chart CPT validation, and reusable-block ref expansion. Frontend renders no longer pay for usage index writes.

Mobile float crop

Floated synced charts (alignleft / alignright) now cap at max-width: 100%, matching aligncenter, so a 420px chart in a ~310px content column no longer crops on mobile.

Fonts & node fills

  • Net value labels resolve font tokens and custom text; default font size raised to 12px. Diff column header font token no longer falls back to browser serif.
  • Node Fill "White" on dot plots (and other node-bearing charts) goes through the same light-dark() color resolver as the rest of the config, so react-spring can interpolate the fill and white fills stay dark-mode aware.

ScreenshotOne credential redaction

API error payloads no longer leak ScreenshotOne credentials.

MIT licensing

@prc/chart-builder and @prc/charting-library declare MIT consistently across package.json, composer.json, plugin headers, and README, and each ships a LICENSE file.

Behind the scenes

  • Field registry sync — npm run sync:field-registry / --check keeps editor controls, theme schema, and seed JSON aligned; wired into the plugin build script.
  • Curated controls shell — Configure / Style Chart step uses a shared curated-controls surface (src/shared/curated-controls/) reused by the CPT wizard and (where applicable) the editor redesign path.
  • Wizard chrome — shared full-layout chrome (src/shared/wizard-chrome/) for the creation flow, including step progress, explainers, and preview toolbar.
  • Viewport documentation — viewport-attributes.md, viewport-breakpoints.md, and viewport-usage-guide.md expanded for authoring responsive overrides.
  • Open-source charting library (PRC-595) — prc-charting-library ships to its standalone consumer repo as part of the open-source readiness track.
  • @wordpress/url in IAPI modules — chart view script modules import @wordpress/url instead of reading window.wp.url, fixing races when the classic script is missing.
  • Geo-points map style — @prc/charting-library can overlay explicit lat/lon points on world maps (dataRender.mapStyle === 'geo-points'). Chart Builder inspector map-style options remain choropleth and bubble; geo-points is a library capability for consumers such as Religious Projections.
  • Version alignment — @prc/chart-builder, @prc/charting-library, and @prc/charting-utilities published versions move to 3.14.0.

Files Changed (high level)

AreaChange
src/controller/chart-cpt-wizard-shell.jsxCPT-hosted creation wizard (Pattern → Data → Configure → Preview)
includes/admin/src/components/chart-wizard.jsxCompact modal wizard for classic placeholder
includes/admin/src/utils/configure-preview/Pure table→chart helpers + debug surface
includes/settings/class-creation-ui-settings.phpSite-level wizard rollout toggle
includes/class-chart-static-images.php + patterns endpointGallery PNG thumbnails + cached chart-patterns REST
includes/settings/chart-theme.json + field registryTheme seed + schema-bound import/export
includes/settings/class-theme-*.phpTheme admin, delivery scoping, cache invalidation
src/shared/curated-controls/Shared Configure / Style controls, including PaletteSwatchPicker
src/chart/edit/bee-swarm-controls.jsxNew — beeswarm inspector
src/chart/edit/waffle-controls.jsxNew — waffle inspector
src/chart/edit/heat-map-table-controls.jsxNew — heat map table inspector
src/chart/edit/tooltip-template-control.jsxNew — RichText tooltip template
src/controller/variations.js + variation templatesRegister beeswarm, waffle, small-multiples, heat-map-table
prc-charting-library Small Multiples / Waffle / BeeSwarm / HeatMapTableNew chart family components
prc-charting-utilities heat map + radius scale + nice domainLayout/cell helpers, createPointRadiusScale, resolveScaleNice
prc-block-tables validationGeo schema catchers, validationMessage, Table data panel guidance
Synced-chart usage / mobile cropPublish-pipeline tracking; max-width: 100% on floats

Upgrade Notes

  • No database migrations. All new attributes are additive with safe defaults.
  • No breaking changes to published content. Existing charts continue to render identically.
  • Creation wizard is opt-in per site. Classic picker remains the default until an administrator enables the new creation UI. Library Add New Chart always opens a new chart post; the wizard appears there when the flag is on.
  • Chart Theme config is forward-only. Changing Chart Settings defaults does not rewrite existing charts; only newly inserted charts pick up theme.config. Palette changes are retroactive for charts that reference a palette slug.
  • Nice domain defaults on. dependentAxis.nice is true so existing charts keep v1.12 rounding. Turn the toggle off when typed min/max must stay exact.
  • Theme delivery is scoped. Anything that previously assumed window.prcChartBuilderTheme was present on every page must enqueue a chart-builder bundle (or read the option server-side) first.
  • Map data guidance lives on the table. Producers should look at the Power Table Table data panel (not the controller inspector) for FIPS / ISO / CBSA requirements and sample CSVs. Misnamed geo headers will fail validation.
  • Tooltip format stays as fallback. Charts that never set tooltip.template keep rendering their mustache format string. Do not backfill template onto existing content.
  • Beeswarm / waffle / heat-map-table / small-multiples / scatter size column require a rebuild of @prc/charting-library, @prc/charting-utilities, and @prc/chart-builder before deploy:
npx turbo build --filter=@prc/charting-utilities --filter=@prc/charting-library --filter=@prc/chart-builder
  • Small Multiples is BETA. Prefer it for new work; Freeform nesting remains available for layouts the compositor does not yet cover.

Tracked Issues

Changesets

  • .changeset/chart-builder-configure-preview-data-helpers.md
  • .changeset/calm-charts-rollout.md
  • .changeset/chart-library-replaces-all-charts.md
  • .changeset/chart-library-performance.md
  • .changeset/library-add-new-chart-post.md
  • .changeset/chart-theme-json-import-export.md
  • .changeset/chart-theme-schema-binding.md
  • .changeset/prc-628-chart-theme-delivery.md
  • .changeset/prc-637-small-multiples.md
  • .changeset/waffle-chart-types.md
  • .changeset/beeswarm-chart-type.md
  • .changeset/heat-map-table.md
  • .changeset/scatter-variable-dot-sizing.md
  • .changeset/chart-swatch-picker.md
  • .changeset/tooltip-template-revamp.md
  • .changeset/axis-domain-legacy-parity.md
  • .changeset/prc-541-nice-domain-toggle.md
  • .changeset/prc-437-mirror-negative-bar-label-dx.md
  • .changeset/prc-640-group-band-scale.md
  • .changeset/prc-553-bar-zero-baseline.md
  • .changeset/prc-660-first-last-line-nodes.md
  • .changeset/chart-builder-map-table-requirements.md
  • .changeset/chart-validation-field-warning.md
  • .changeset/chart-id-copy-detection.md
  • .changeset/synced-chart-usage-pipeline-request-memo.md
  • .changeset/fix-synced-chart-mobile-crop.md
  • .changeset/fix-wizard-preview-viewport-toggle.md
  • .changeset/fix-net-value-font-family-token.md
  • .changeset/fix-node-fill-white-color-resolution.md

Was this helpful?