PRC Block Library

The core Gutenberg block library for the PRC Platform — provides all custom blocks and core block enhancements used across pewresearch.org.

Overview

PRC Block Library registers ~90 blocks across two namespaces: prc-block/* for custom PRC blocks and modifications to core/* blocks. It is the display layer of the platform and the first plugin loaded when rendering any content. Beyond blocks, it also ships a set of cross-cutting support systems (Interactivity API helpers, a Print Engine, block visibility controls, custom rich text formats, sticky/legacy-max-width layout supports, and a form data store) that apply globally to all registered blocks.

In the block editor, the plugin registers the Pew Research Center Block Library block collection (namespace prc-block) in includes/supports/src/index.jsx, which is enqueued with the Supports subsystem.

Dependencies

• Upstream: prc-platform-core (required plugin), prc-schema-seo (optional, for PDF contact resolution), prc-staff-bylines (optional, for PDF bylines), Report Package plugin (optional, for multi-chapter PDF rendering), WordPress AI plugin (optional, for tabular data AI experiment)
• Downstream: Every plugin or theme that renders blocks on the front end depends on this library. Form input blocks (prc-block/form-input-*) live here; the form container and related blocks live in @prc/block-forms. The prc-block-library/forms @wordpress/data store (registered by @prc/block-forms) is a direct integration point for any plugin registering custom form types.

Local Development Setup

Prerequisites

• Node.js 22+ / npm 10.9+
• PHP 8.2+
• WordPress Playground (via `npm run vip:start from repo root)

Running Locally

# Build the entire library (run from repo root)
npm run build:library -w @prc/block-library

# Build a single deprecated block only
npm run build deprecated:grid-controller -w @prc/block-library

# Watch mode for a single deprecated block during development
npm run start deprecated:grid-controller -w @prc/block-library

# Watch mode for the full library
npm run start:library -w @prc/block-library

Running Tests

# Run Playwright e2e tests (from monorepo root; VIP dev-env + Playwright are centralized)
npm run vip:start
npm test -- tests/prc-block-library/e2e/

Architecture

Blocks are discovered and loaded automatically at runtime. Plugin::load_blocks() globs all subdirectories of src/ (in local/dev) or build/ (in production) and calls include_block() for each. Any directory prefixed with _ or . is skipped. Each block is expected to have a class-{block-name}.php file which self-registers with WordPress using register_block_type_from_metadata(). Block metadata is pre-indexed at build time via build/blocks-manifest.php and registered with wp_register_block_metadata_collection() for performance.

Blocks are split into two groups initialized by Plugin:

• Core blocks (define_core_blocks): extensions and modifications to existing core/* blocks — adding attributes, context, controls, or custom rendering.
• PRC blocks (define_prc_blocks): net-new blocks in the prc-block namespace.

In addition to block classes, Plugin boots several support subsystems via define_library_dependencies(). These run independently of individual blocks and hook into WordPress globally.

Block scaffolding uses @wordpress/create-block with templates located at the repository root (/block-templates). There are four variants:

To scaffold a new block, run npm run create-block from the repository root. See /block-templates/README.md for detailed documentation.

Key Files

Blocks

This section doubles as the documentation index. Each block links to its detailed doc in docs/plugins/prc-block-library/blocks/.

Core Block Modifications (core/*)

Adds attributes, context, rendering changes, or new editor controls to existing WordPress core blocks.