Canonical docs: docs/plugins/prc-block-bits/

Inline-RichText "bits" registry, central render-block walker, and editor toolbar.

prc-block-bits provides a shared registry and a single-pass render-block walker for bits — small pieces of dynamic content that live inside a string of static text (mid-paragraph, mid-heading), inside any RichText-bearing block. It also ships an editor toolbar for inserting bits and a set of built-in bits.

For agent-oriented architecture and third-party registration steps, see AGENTS.md.

Use a bit when you need dynamic content inside a string of static text (mid-paragraph, mid-heading). Use block bindings when the whole block's content is dynamic. The two are not interchangeable; bits are inline-RichText, bindings are block-level.

These bits register on init (priority 11) from includes/bits/ and are always available when the plugin is active (unless disabled in Settings → Block Bits).

All three use an edit component in the editor (attribute picker before insert). Implementation lives under src/editor/builtins/.

Third-party plugins register additional bits via register_block_bit() — see AGENTS.md and the examples in prc-quiz-political-typology-2026.

The icon-span bit prefers \PRC\Platform\Icons\has_registry_icon() / get_registry_icon_svg() for curated UI glyphs (PRC-724). Approved brands use collection brands. Missing names fail closed.

1. Activate prc-icon-library — defines PRC_PLATFORM_ICONS_URL and PRC_PLATFORM_ICONS_PATH pointing at build/icons/ (prc.svg and brands.svg).
2. prc-shared exposes \PRC\Platform\Icons\get_icon_as_url( $library, $icon ), which resolves URLs as {PRC_PLATFORM_ICONS_URL}{prc|brands}.svg#{icon}.
3. prc-block-bits localizes window.prcBlockBits.iconSpritesUrl (same base URL) for editor fill-sprite previews on icon-span bits.
4. The icon-span picker opens Gutenberg's registry modal (getEntityRecords('root', 'icon')). IconPicker from @prc/components is no longer used here.

See prc-icon-library/README.md for fill sprites, build steps, and render helpers.

To serve icons from your own plugin (or replace the default fill sprites):

1. Expose fill sprite files — Host SVG sprites that follow the same shape: prc.svg and brands.svg with <symbol id="icon-name"> entries. Icons are referenced as {baseUrl}prc.svg#icon-name.

2. Define the platform constants (typically in your plugin’s main file, on load):

   define( 'PRC_PLATFORM_ICONS_URL', plugin_dir_url( __FILE__ ) . 'assets/icons/' );
   define( 'PRC_PLATFORM_ICONS_PATH', plugin_dir_path( __FILE__ ) . 'assets/icons/' );

   Load before icon rendering runs. If PRC_PLATFORM_ICONS_URL is undefined, get_icon_as_url() returns an HTML comment and icon-span renders an empty span.

3. Editor index — Regenerate @prc/icons’s icon-library-index.json so IconPicker lists your libraries and icon names:

   node plugins/prc-shared/includes/scripts/src/@prc/icons/bin/build-index.js
   npx turbo build --filter=@prc/icons

   The build script copies curated-prc-icons.json (prc and brands name lists).

4. Optional: override editor sprite base — Assets sets window.prcBlockBits.iconSpritesUrl from PRC_PLATFORM_ICONS_URL when defined. Icon-span editor preview falls back to /wp-content/plugins/prc-icon-library/build/icons/ only when the constant is missing; defining the constant from your provider is the supported path.

Same-origin note: Sprite <use href="…"> references must be same-origin with the page. Serve sprites from the site’s domain (or a CDN configured as same-origin).

\PRC\Platform\Block_Bits\register_block_bit(
    'my-plugin/my-bit',
    array(
        'label'                => __( 'My bit', 'my-plugin' ),
        'category'             => 'Quiz', // optional; groups bits in the modal picker
        'allowed_block_types'  => array( 'core/paragraph', 'core/heading' ),
        'attributes'           => array(
            // Per-attribute schema. `type` is one of:
            //   'string' | 'int' | 'hex_color' | 'icon_name' | 'enum' | …
            // Used by the walker for harvest-time sanitization.
            'icon-name' => array( 'type' => 'icon_name' ),
        ),
        'render_strategy'      => 'callback', // 'iapi' | 'callback'
        'render_callback'      => function ( array $attrs, array $parsed_block, ?\WP_Block $block ): string {
            return '<span class="prc-block-bit">' . esc_html( $attrs['icon-name'] ?? '' ) . '</span>';
        },
        'default_text'         => 'fallback', // request-deterministic; see below.
    )
);

default_text MUST be request-deterministic. It must resolve to the same string for every request to a given URL — no current_user_can(), no wp_get_current_user(), no time-of-day variation. The edge cache treats the rendered HTML as cacheable; per-user fallback text would poison shared cache entries. The registry rejects callable default_text values, and WP_DEBUG runtime checks fire _doing_it_wrong() on per-user variance.

import { registerBlockBit } from '@prc/block-bits';

registerBlockBit('my-plugin/my-bit', {
	title: __('My bit', 'my-plugin'),
	icon: someIcon,
	edit: SomeInlinePicker, // optional — only needed for attribute-bearing bits
});

In the monorepo, import @prc/block-bits from a bundle built with the root webpack.config.js so dependency extraction resolves the prc-block-bits-editor script handle.

• iapi — declarative Interactivity API directives are emitted onto the bit's <span> (data-wp-interactive, data-wp-text, data-wp-bind--*, optional data-wp-context). Cross-context fallback: if the iAPI namespace isn't mounted on the page, the editor-written default_text persists as visible textContent.
• callback — pure-PHP render_callback returns a string that replaces the bit's <span> outer HTML. Callbacks run inside a try/catch wrapper and their output passes through a central wp_kses() allowlist before substitution.

A single late-priority render_block filter (priority 100) with a mandatory str_contains( $content, 'prc-block-bit' ) early-exit, followed by a WP_HTML_Tag_Processor walk for iAPI bits and a WP_HTML_Processor-backed pass for callback bits.

When more than five bits apply to the current block, the toolbar opens a modal with category groups and a search field. Uncategorized bits appear under General. Bits can be disabled site-wide under Settings → Block Bits.