Directives to execute a callback in the scope of the component

[luisherranz]

Right now we have two directives to use useEffect: wp-effect and wp-init.

wp-effect is reactive and runs each time state or context change, which is very handy. This is its code (simplified):

useSignalEffect(() => {
  return evaluate(reference); // reference is for example effect.someEffect
});

And wp-init is not reactive and only runs when the element is created. This is its code (simplified):

useEffect(() => {
  return evaluate(reference); // reference is for example init.someInit
}, []);

But sometimes you may want to execute code in the scope of the component outside of any useEffect, because you want to use your own useEffect. For example:

import { store } from "@wordpress/interactivity";
import useInView from "some-use-in-view-react-hook-library";

store({
  effects: {
    someEffect: ({ context, ref }) => {
      const isInView = useInView(ref);

      useEffect(() => {
        if (isInView) {
          // Do something here when the component is in the viewport.
        } else {
          // Do something here when the component is not in the viewport.
        }
      });
    },
  },
});

So, maybe we need a third directive for this, or modify the other two to accommodate for this possibility.

Suggestions are welcomed 🙂

[luisherranz]

I've been trying to make a reusable isInView function that works inside the useEffect directives without success. Basically, I want to abstract this type of logic

store({
  effects: {
    isInView: ({ context, ref }) => {
      const observer = new IntersectionObserver(([entry]) => {
        context.status = entry.isIntersecting ? "Inside" : "Outside";
      });
      observer.observe(ref);
      return () => observer.unobserve(ref);
    },
  },
});

into a composable function that others can use, like this:

store({
  effects: {
    isInView: ({ context, ref }) => {
      context.status = isInView(ref) ? "Inside" : "Outside";
    },
  },
});

The problem is that the callback that you pass to useEffect is not considered part of the render method, and therefore you cannot use other hooks inside it to store a stable reference.

So if you try to put something like this inside a useEffect, it fails with Uncaught Error: Hook can only be invoked from render methods.

const useInView = (ref) => {
  const [isInView, setIsInView] = useState(false);

  useMemo(() => {
    const observer = new IntersectionObserver(([entry]) => {
      setIsInView(entry.isIntersecting);
    });
    observer.observe(ref);
  }, []);

  return isInView;
};

const Comp = () => {
  const ref = useRef();

  useEffect(() => {
    const inView = useInView(ref.current); // Error!
  });

  // ...
};

Also, the destroy callback (() => observer.unobserve(ref)) is missing, and you would have to pass it explicitly somehow:

const useInView = (ref) => {
  const [isInView, setIsInView] = useState(false);
  const observer = useRef(null);

  useMemo(() => {
    observer.current = new IntersectionObserver(([entry]) => {
      setIsInView(entry.isIntersecting);
    });
    observer.current.observe(ref);
  }, []);

  return [isInView, () => observer.current.unobserve(ref)];
};

Like this in Preact:

const Comp = () => {
  const ref = useRef();

  useEffect(() => {
    const [inView, clean] = useInView(ref.current); // Error!
    // Use inView...
    return clean;
  });

  // ...
};

And like this in the Interactivity API:

store({
  effects: {
    isInView: ({ context, ref }) => {
      const [isInView, clean] = isInView(ref);
      context.status = isInView ? "Inside" : "Outside";
      return clean; // Explicit.
    },
  },
});

There may be workarounds to the fact that hooks cannot be used inside useEffect, like using a WeakMap linked to the ref to simulate stability, but they are not as straightforward as using plain React hooks, and the need to explicitly return the destroy callback remains: example

On the other hand, the directives we have right now are just syntax sugar for useEffect:

• data-wp-init:

  useEffect(() => {
    // The code of the reference.
  }, []);

• data-wp-effect:

  useSignalEffect(() => {
    // The code of the reference.
  });

So I've started wondering if instead of adding yet another effect function, which may introduce confusion about when to use what, we should delegate effects to Preact and just have a single data-wp-evaluate directive where people can add their own useEffect, useSignalEffect or whatever combination of hooks they need.

Any thoughts?

---

If you want to play with this:

• Stackblitz of the isInView logic using data-wp-init in case you want to try figuring out a way to abstract it into a reusable function.
• Stackblitz of a reusable hook useInView using data-wp-evaluate

[luisherranz]

So I've started wondering if instead of adding yet another effect function, which may introduce confusion about when to use what, we should delegate effects to Preact and just have a single wp-evaluate directive where people can add their own useEffect, useSignalEffect or whatever combination of hooks they need.

After more thought, maybe it's not that problematic to keep wp-init, wp-effect and introduce a new wp-evaluate. At least for now, until we learn more about the use cases for wp-evaluate.

Any thoughts?

[luisherranz]

If we don't replace data-wp-init and data-wp-effect with data-wp-evaluate, people will also eventually need access to useLayoutEffect (and useLayoutSignalEffect), which would add two more directives: data-wp-layout-init and data-wp-layout-effect.

[luisherranz]

After a lot of thinking, this is my proposal for this discussion.

• In the docs, we keep saying that both state and context are reactive, but we avoid the word "signal".
• We expose the useSignalEffect hook, but we rename it to useWatch. We explain that it is re-executed each time a reactive variable changes.
• We rename the data-wp-effect directive to data-wp-watch. That way, we avoid the confusion between data-wp-effect (which is reactive) and useEffect (which is not reactive).
• We keep the data-wp-init directive.
• To keep consistency, we also expose a useInit hook (which is sugar for useEffect(cb, []))
• We create a data-wp-run directive where you can use any hook, including useWatch, useInit, useEffect and useLayoutEffect.

I'm not sure if it will be needed at some point or not, but in the future we could create a useLayoutWatch hook and/or a useLayoutInit hook.

So we end up with these "hook" directives:

• data-wp-init and useInit: they run when the element is created and if you return a callback, it runs when the element is destroyed. You can't run any hooks inside it.
• data-wp-watch and useWatch: they run when the element is created and when a tracked reactive variable changes. If you return an element, it runs before the previous execution and when the element is destroyed. You can't run any hooks inside it.
• data-wp-run: it runs when the element is created and each time it is rerendered. You can run any hooks in it, including the previous ones.

For the store, it's not going to be enforced but we need a standard property name to store that logic. We could keep the word effects, but I think it's not clear anymore.

We could use separate words, although the plurals of init, watch and run sound a bit weird:

store("myPlugin", {
  state: {
    // ...
  },
  actions: {
    // ...
  },
  inits: {
    // ...
  },
  watches: {
    // ...
  },
  runs: {
    // ...
  },
});

Or we could coin a new name that attempts to unite the three types. My two preferred alternatives are callbacks and hooks.

callbacks is simple and generic.

store("myPlugin", {
  state: {
    // ...
  },
  actions: {
    // ...
  },
  callbacks: {
    // ...
  },
});

hooks has more meaning, which is good if we call these directives the "hook" directives, although it also conflicts with the other uses of the word "hook" in React/WordPress.

store("myPlugin", {
  state: {
    // ...
  },
  actions: {
    // ...
  },
  hooks: {
    // ...
  },
});

cc: @SantosGuillamot, @DAreRodz, @juanmaguitar

[DAreRodz]

I like the proposed directives and the Interactivity API store's state, actions, and callbacks properties.

Regarding the data-wp-run directive, I understand its callback will run during the element rendering, right? Would it make sense to make the element props available there? Currently, only the directives logic can access the props of the rendered element.

[DAreRodz]

That could be useful for retrieving info from the element instead of relying on the DOM (ref). It could also be an opportunity to modify some element prop if desired. 🤔

[luisherranz]

Regarding the data-wp-run directive, I understand its callback will run during the element rendering, right?

It runs each time the component is rendered. It's basically something like this:

const Component = ({ element }) => {
  // data-wp-run is executed here.

  useEffect(() => {
    // data-wp-init is executed here.
  }, []);

  useSignalEffect(() => {
    // data-wp-watch is executed here.
  });

  return element;
};

Would it make sense to make the element props available there?

That's a great idea.

Would you like to open a new discussion to explore that option and add it to the roadmap? 🙂

[SantosGuillamot]

First of all, thanks a lot for the information and the research here 🙂 And sorry for not answering in the previous comments, it was in my to-do list for a long time.

I like the idea of having data-wp-init and data-wp-watch, which seem the most common use cases, and data-wp-run to provide more flexibility for developers.

Regarding the store properties, I agree that effects could be confusing and harder to explain, and I don't like having separate words either. Between callbacks and hooks I'm more inclined to callbacks. As you say, I feel we are using "hooks" in many places and it can become confusing (React hooks, WordPress hooks, now we also have Block hooks...)

[luisherranz]

This was finally added as data-wp-run in WP 6.5.

Closing this as completed 🙂