⚠️ Experimental / Prototype Work

This PR is NOT ready for merge as-is. It's intentionally large to demonstrate the complete UI experience and developer interface for custom navigation link bindings. Before shipping, this needs to be broken into smaller, focused PRs.

Purpose: To allow reviewers and stakeholders to:

• Envision the end-user UI experience in the editor
• Understand the developer interface for creating custom binding sources
• Provide feedback on the overall approach before we invest in breaking it down

Next steps: After review and consensus, we'll split this into logical incremental PRs that can be safely merged.

What

Enables Navigation Link blocks to use any registered block binding source, not just core/post-data and core/term-data. Binding sources control link editability through their canUserEditValue function.

Why

Navigation Links were hardcoded to only work with two core binding sources. This prevented plugins from creating custom binding sources for navigation links—use cases like WooCommerce policy pages, custom settings pages, or plugin-managed links.

How

The block now accepts any registered binding source instead of hardcoding allowed sources. Link editability is controlled by the binding source's canUserEditValue function: when it returns false, the URL becomes read-only while the label remains editable. Core binding sources (core/post-data, core/term-data) remain editable for navigation blocks, while custom sources can enforce read-only behavior as needed.

Also fixes a bug where draft pages were incorrectly badged as "Homepage" in the editor.

Testing Instructions

Test 1: Regular Navigation Links

1. Insert a Navigation block
2. Add Page and Post links
3. Expected: Links remain editable via sidebar controls

Test 2: Custom Read-Only Binding Source

1. Create a custom binding source with canUserEditValue: () => false:

wp.blocks.registerBlockBindingsSource( {
    name: 'my-plugin/custom-source',
    label: 'My Custom Source',
    getValues( { bindings } ) {
        const results = {};
        const { select } = wp.data;
        
        // Example: Link to privacy policy from WordPress settings
        const settings = select( 'core' ).getEntityRecord( 'root', 'site' );
        const pageId = settings?.wp_page_for_privacy_policy;
        
        if ( pageId ) {
            const page = select( 'core' ).getEntityRecord( 'postType', 'page', pageId );
            if ( page ) {
                if ( bindings.url ) results.url = page.link;
                if ( bindings.id ) results.id = page.id;
            }
        }
        
        return results;
    },
    // Both setValues and canUserEditValue must be defined
    setValues() {
        // No-op for read-only sources
    },
    canUserEditValue() {
        return false; // Makes the link read-only
    },
    usesContext: [],
} );

2. Register server-side equivalent:

register_block_bindings_source(
    'my-plugin/custom-source',
    array(
        'label'              => 'My Custom Source',
        'get_value_callback' => function ( $source_args, $block_instance, $attribute_name ) {
            $page_id = get_option( 'wp_page_for_privacy_policy' );
            if ( ! $page_id ) {
                return null;
            }
            
            if ( 'url' === $attribute_name ) {
                return get_permalink( $page_id );
            }
            if ( 'id' === $attribute_name ) {
                return (int) $page_id;
            }
            return null;
        },
        'uses_context'       => array(),
    )
);

3. Create a navigation link using the custom binding:

<!-- wp:navigation-link {"label":"Privacy Policy","type":"page","kind":"post-type","metadata":{"bindings":{"url":{"source":"my-plugin/custom-source","args":{}},"id":{"source":"my-plugin/custom-source","args":{}}}}} /-->

4. Expected:
   • Link displays with correct URL
   • Label is editable
   • URL is locked (button disabled, no dropdown arrow)
   • Frontend renders correctly

Test 3: Homepage Badge Fix

1. Create a draft page
2. Add it to navigation
3. Expected: Shows "Page" + "Draft" badges (NOT "Homepage")

Implementation Notes

• API Requirement: canUserEditValue is only registered if setValues is also defined (even for read-only sources, add a no-op setValues)
• Core binding sources return true for navigation blocks (they use attributes instead of context for entity data)
• Custom binding sources can return false to create read-only links