Magento 2 Admin Grid Filter – How to Fix Filter Lost on Reload

Try this:

$this->joinTable(
    'catalog/category_product', // table to join
    'product_id=entity_id', // ON statement, flat table first!
    array(), // don't add any columns
    array('in' => $categoryIds) // additional WHERE
);

Of course, as per usual, I figured it out right after posting my question... Argh... I'll post the solution since there is a frustrating lack of documentation about M2.

This part of my grid block file was modified as follows

public function getGridUrl()
{
    return $this->getUrl(
        'customproducts/*/reloadgrid', ['_current' => true, 'collapse' => null]
    );
}

the getUrl() method is given the path to a new controller I use to reload the grid (through customproducts/*/reloadgrid parameter).

Here is the content of the new controller

Morello/Customproducts/Controller/Adminhtml/Index/ReloadGrid.php

<?php

namespace Morello\Customproducts\Controller\Adminhtml\Index;

use Magento\Framework\App\Action\Action;
use Magento\Framework\App\Action\Context;
use Magento\Framework\App\ResponseInterface;
use Magento\Framework\Controller\Result\Raw;
use Magento\Framework\View\Result\PageFactory;

class ReloadGrid extends Action
{
// Let's get down to business, shall we?
    protected $resultPageFactory;
    protected $resultInterface;
    protected $resultRaw;

    /**********************************************************************
    *
    * In the construct I collect the info I'll need in the execute() method
    * namely the PageFactory, ResultPageFactory and Raw result to provide
    * the interface the method must return
    *
    ***********************************************************************/

    public function __construct(Context $context, PageFactory $resultPageFactory, Raw $resultRaw)
    {
        $this->resultPageFactory = $resultPageFactory;
        $this->resultRaw = $resultRaw;
        parent::__construct($context);
    }

    /**********************************************************************
    *
    * This is where it got tricky for me.
    * I'll walk through the steps one by one (because I wish someone would
    * have done it while I was searching for a solution...)
    *
    ***********************************************************************/

    public function execute()
    {   
        // First step is to create a ResultPageFactory
        // to retrieve the result for the filtered table
        $resultPage = $this->resultPageFactory->create();

        // In order to update the grid we can reload the original
        // block used to render it in the first place but if you
        // look at my question you'll see that my template file
        // 'customerproducts_index_customer.xml' has a nested
        // structure with the grid block/class already inside 
        // a couple of blocks, so rather than refactoring that
        // I created a new template just for reloading the grid
        // which I called 'customproducts_search_grid_handle.xml'
        // for simplicity. (content is attached below)

        // Second step is to provide the block to render to the 
        // ResultPageFactory we instantiated in step 1 by passing
        // our handle name
        $resultPage->addHandle('customproducts_search_grid_handle');

        // Once our ResultPageFactory knows what we want we can
        // Ask it to extract the layout and render the element 'content'
        $result = $resultPage->getLayout()->renderElement('content');

        // This was the trickiest step for me. Since the execute mthod
        // of Magento\Framework\App\Action\Action must return either
        // a ResultInterface or a ResponseInterface I needed to find
        // a class that would allow me to get the content in the desired
        // format so I used Magento\Framework\Controller\Result\Raw
        // which extends AbstractResult which extends ResultInterface
        // and then we can call the setContents() method providing
        // the element we rendered in the 3rd step...
        return $this->resultRaw->setContents($result);

        // Easy-Peasy right?
    }
}

Here is the content of the new layout for the handle

Morello/Customproducts/view/adminhtml/layout/customproducts_search_grid_handle.xml

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceContainer name="content">
            <block class="\Morello\Customproducts\Block\Adminhtml\Edit\Page\SearchProductGrid" name="customer_product_search_grid" as="customer_product_search_grid" />
        </referenceContainer>
    </body>
</page>

As you can see it just contains the instance of the block we already used when creating the grid the first time.

I hope this helps somebody avoiding a few days of despair.