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.

Content & Editorial (prc-block/*)

Navigation & Layout

Interactive UI

Forms

Form container and structure blocks (prc-block/form, form-page, form-submit, form-message, form-captcha, form-message-bindings) are registered by @prc/block-forms. Form input blocks remain in this plugin:

Social

Taxonomy & Data

Attachments & Media

Utilities & Developer Tools

Support Systems

These subsystems are booted by Plugin and apply globally, not per-block.

Interactivity API (includes/interactivity-api/)

Injects interactiveNamespace (string) and interactiveSubsumption (boolean) attributes on every block that declares "interactivity": true in its supports. Also wires prc-block/interactiveNamespace into usesContext and providesContext so namespace values flow down the block tree automatically.

Print Engine

Print / PDF document generation lives in the standalone prc-print-engine plugin (/print endpoint and Block_Print_Registry). Block-library still registers print styles for blocks such as core/post-title on prc_print_engine_register_block_callbacks.

Block Supports (includes/supports/)

Adds sticky layout enhancements for blocks that support sticky positioning:

• Sticky enhancements — isStuckBackground, isStuckText, isStuckBoxShadow attributes that swap colors and add a box shadow when a sticky block is in the "stuck" state via the Interactivity API.
• Legacy maxWidth — the Dimensions panel Max Width control is removed. Existing blocks that already have a maxWidth attribute keep editor and frontend styling. Prefer Gutenberg content width / layout settings for new content; custom CSS remains available for one-off cases.

The same editor script (src/index.jsx) unregisters unused core block types (archives, calendar, latest comments, tag cloud, verse) and a set of core/embed service variations; edit that file to change the list.

Form Data Store

The prc-block-library/forms @wordpress/data store is registered by @prc/block-forms (see plugins/prc-block-forms/src/form/store.js). Form types are registered through that store rather than WordPress filters.

import { dispatch } from '@wordpress/data';

dispatch('prc-block-library/forms').registerForm({
    label: 'My Custom Form',
    namespace: 'my-plugin/namespace',
    action: 'my-action',
    method: 'api',
    template: [
        /* block template */
    ],
});

Retrieve registered forms:

import { useSelect } from '@wordpress/data';

const forms = useSelect(
    (select) => select('prc-block-library/forms').getForms(),
    []
);

Hooks & Filters

Block patterns (disposition-A scaffolds)

Patterns live in patterns/ and register via register_plugin_patterns() from client-mu-plugins/plugin-patterns.php. Category slug: prc-block-library.

Use the Patterns inserter (prc-block-library category) for these scaffolds.

core/group width presets (transform-scoped variations)

Constrained-width group presets (200px, 250px, 300px, 320px, 420px, 640px) register as core/group block variations with scope: ['transform'] in src/core-group/variations.js. They appear in the block transforms menu when converting or transforming a Group block, not in the block inserter, Patterns inserter, or variation switcher.

core/heading presets (transform-scoped variations)

Heading (H4 default), Section (isChapter: true, level 3), and Layout Heading (is-style-layout-heading) register as core/heading block variations with scope: ['transform'] in src/core-heading/index.js. They appear in the block transforms menu only.

Binding companions (patterns + inserter variations)

Copyright disclaimer remains a parent-scoped pattern. Tab label, dialog label, form result message, and version info register as block variations visible in the block inserter only (not the variation switcher). Use Attributes → Bindings to retrofit existing blocks.

Author discovery (bindings, patterns, bits)

Troubleshooting

Block class not found on activation

Symptom: Fatal error referencing a missing class (e.g. Core_Button) on plugin load.
Cause: A block directory exists in build/ but its class-{block-name}.php file is missing — usually because the library was not built after a fresh clone.
Fix: Run npm run build:library -w @prc/block-library from the repo root.

Block not appearing in the editor

Symptom: A block is not visible in the block inserter after adding its directory to src/.
Cause: The new block class was not initialized in Plugin::define_prc_blocks() or Plugin::define_core_blocks(), or its directory name starts with _ or ..
Fix: Add new My_Block($this->get_loader()); in the appropriate method in includes/class-plugin.php and rebuild.

?pdf=true page is blank or crashes

Symptom: The print/PDF view renders nothing or throws a PHP error.
Cause: The Print Engine exits early if is_singular() is false, or if $post is null. Can also happen when the prc-block/table-of-contents block's render.php is not built.
Fix: Confirm the URL is for a singular post type, that the library is fully built, and that prc-block/table-of-contents appears in build/blocks-manifest.php.

Related Docs

• Development Guidelines
• JavaScript Development Rules
• WordPress Development Rules
• Block Development Skill
• Interactivity API Skill