The data-wp-client-only-component directive

[luisherranz]

Let's start working on a directive that allows loading Preact components directly into the Interactivity API 🙂

First, for anyone reading this, it's very important to understand that these Preact components cannot be rendered in PHP and, therefore:

1. The HTML they generate will not be rendered by the server and will not appear in the initial HTML.
2. The HTML they generate will be hidden from PHP so it cannot be modified by WordPress filters and plugins.

Therefore, these components should only be used for HTML that doesn't need to be filtered and that isn't displayed in the initial rendering of the page.

Let's hope that the developers understand, simply from the directive's name, that these components only work on the client. However, the documentation should also be very explicit.

That said, there are legitimate use cases for wanting to include this type of components in the frontend. So, let’s explore how it might work.

The directive itself is very simple at the code level, as internally, the Interactivity API is using Preact, so it’s enough to pass the component to the Interactivity API internals.

directive(
  'client-only-component',
  ({ directives: { ['client-only-component']: comp }, element, evaluate }) => {
    const entry = comp.find(({ suffix }) => suffix === null);
    return evaluate(entry)(element.props);
  }
);

Initially, my idea is that it works as follows:

• The element that contains data-wp-client-only-component will be replaced in the DOM with the Preact component.

  There's also the possibility that the Preact component can be added as a child, but it seems less flexible and intuitive to me.

• The attributes of the element with the directive are passed as props to the component.

• The Preact components can access the hooks by importing them directly from @wordpress/interactivity.

  There's also the possibility of importing them directly from preact by adding another entry to the import map, Since the hooks are slightly modified to work perfectly within data-wp-run. This is something we need to study carefully.

• The Preact components can access the stores of the Interactivity API: they can read and modify the global state and the local context, and execute actions.

  They can simply do this by using store('myPlugin'), or getContext('myPlugin'). Everything should be reactive: when mutating state, or getContext, the components accessing those properties will re-render.

• The HTML rendered on the server as a child of the element containing the directive data-wp-client-only-component, will be passed to the component, using the children prop. This means that Preact components and rendered HTML can be interleaved on the server. This HTML can also include directives.

I've created a prototype using StackBlitz that demonstrates how this type of component would work, and I've tried to cover all the cases explained here.

<span
  data-wp-client-only-component="components.Comp"
  data-message="This is the current counter"
>

const { state } = store('myPlugin');

export default ({ children, 'data-message': message }) => {
  const [counter, setCounter] = useState(0);
  const context = getContext('myPlugin');

  useEffect(() => {
    console.log(`${message}: ${counter}`);
  }, [counter]);

  return (
    <span>
      Closed {state.timesClosed} times -{' '}
      <button onClick={() => setCounter((c) => c + 1)}>{counter}</button>{' '}
      <button onClick={() => (context.isOpen = false)}>
        Close (component)
      </button>
      {children}
    </span>
  );
};

---

Although the directive is more or less clear, there are still a couple of things left to do:

1. Currently, the evaluate function auto-executes the functions passed by reference. It should be modified to allow passing a flag so that it doesn’t do this for this specific case.
2. We should modify wp-scripts with the --experimental-modules argument, so that it utilizes the JSX of Preact in the frontend modules.

Please, give it a try and share your feedback here.

[michalczaplinski]

Works great, @luisherranz! 🙂

Not a big deal, but I noticed the warning:

Expected a DOM node of type button but found as available DOM-node(s), the SSR causes this'd HTML containing different DOM-nodes compared to the hydrated one.

being fired when using the data-wp-client-only-component. It's coming from preact-debug on this line. Looks like it was added to Preact recently: preactjs/preact#4490

I tried the following to suppress the warning, but alas it does not work as I expected. I think It might be because we don't re-export the options from @wordpress/interactivity.

import { directive } from './private-apis';

// We'd have to re-export Preact's options in the `@wordpress/interactivity` package.
import { options } from 'preact'; 

// data-wp-client-only-component
directive(
  'client-only-component',
  ({ directives: { ['client-only-component']: comp }, element, evaluate }) => {
    options._hydrationMismatch = () => {};
    const entry = comp.find(({ suffix }) => suffix === null);
    return evaluate(entry)(element.props);
  }
);

[michalczaplinski]

Yes, I understand, but do you not think that this warning is misleading?

If we have to explain that the warning showing up actually means that data-wp-client-only-component works as intended then we might as well get rid of it, right? I'm pretty sure that users will complain about seeing this warning and ask how they can disable it.

Another downside is that if we keep this warning, then people will become accustomed to seeing a warning in the console and might miss a legitimate (but different) error because of it.

[luisherranz]

So, what do you suggest? 🙂

[michalczaplinski]

I'd say we find a way to get rid of the warning. I think that once we re-export options in the @wordpress/interactivity package, the snippet I shared above should work correctly.

[luisherranz]

But how do you get rid of this warning without getting rid of all the hydration warnings?

[michalczaplinski]

We probably cannot eliminate hydration warnings only when the data-wp-client-only-component is used.

But let's imagine that we don't do anything. If a user of data-wp-client-only-component makes a genuine error resulting in a genuine hydration warning, they would see not one but two (or more) hydration warnings. So, even if we "inform" the users that they should ignore one of the warnings (related to the data-wp-client-only-component), the user has to figure out which warning is the genuine one and which one isn't.

It just seems like it's not worth the trouble, and we'd be better off without any warnings at all 🙂.