Tracking issue: WordPress Directives Plugin 🎨

[luisherranz]

This issue aims to list and keep track of the tasks related to the WordPress Directives Plugin experiment. The goal is to create an installable plugin that adds a set of basic directives and client-side navigations to any site.

For this experiment's stress-testing, please check the Tracking Issue: Performance and stress-testing vDOM Hydration 🧪

For the Custom Elements or Directives Hydration experiment, please check their corresponding Tracking Issues.

The main branch of this experiment is main-wp-directives-plugin. Make sure you select it when opening a pull request if it is related to this experiment.

Please proactively comment on this issue whenever you start working on a new task, get blocked, or finish a task, sharing as much detail and information as possible. Thanks!!

High-level overview

• Directives

  • Finish the directives of the initial list - In progress 🚧

    Work on the directives is still reactive as we only work on the ones that we need for our experiments, demos, etc. The work on the Movies demo and Woo blocks should bring some focus to this task.

  • Add SSR for the ones that need it - In progress 🚧\

    This is led by @ockham and @dmsnell.

    There's already initial support for the SSR of basic directive attributes and good progress on wp-context. The next challenge to solve is to figure out the APIs to access the inner HTML with the HTML (Tag) Processor.

  • Decide final names - In progress 🚧

    We are keeping a list of the decisions that need to be made here in the Tracking Issue.

• Components

  There hasn't been any progress on this, mostly due to the lack of need for components (directive tags). @luisherranz opened an issue proposing their removal, as we couldn't find a single case where they add meaningful value and we might want to use them for other purposes in the future.

• State Management

  • Finish the Deep Signals implementation - Finished ✅
  • Decide on the recommended shape - In progress 🚧
    Same answer as in the "Directives - Decide final names".
  • TypeScript support - Not started ⏸
  • Figure out if we want to expose some parts of the router and/or other configuration in the state (example) - Not started ⏸

• Server-side rendering

  • API to do SSRing - In progress 🚧
    Same answer as in the "Directives - Add SSR for the ones that need it".
  • Serialize initial state - Finished ✅
  • Sort directives by priority - Not started ⏸

• Client runtime

  • Limit hydration when CSN is not possible Finished ✅
  • Deserialize state Finished ✅ (mostly)
  • Sort directives by priority - In progress 🚧

• Bundling

  • API to register directives/components - Not started ⏸
  • Enqueue directives/components present in the HTML - Not started ⏸
  • Ensure script execution order, deferring and prefetch - Not started ⏸
  • Choose final package name and shape - In progress 🚧
    Same answer as in the "Directives - Decide final names".
  • Choose and implement dependency management - In progress 🚧
    Barely started, just preliminary conversations between @luisherranz, @gziolo, @dmsnell and @youknowriad.

• Client-side navigation

  • Manual (Finished ✅) and automatic opt-in (Not started ⏸)
  • Router
    • Fetch directives/components scripts - Not started ⏸
    • Global state (state.router.url) - Not started ⏸
  • API to trigger virtual pageviews - Not started ⏸
  • Prefetching strategy - Not started ⏸

Done

• 🎨 Add wp-link attribute to all links #81
• 🎨 Add basic functionality #82
• 🎨 Add basic router and wp link directive #83
• 🎨 Remove comments and preserve scripts #84
• 🎨 Support CSS in client-side navigations #85
• 🎨 Add meta tag to opt-in to client-side navigations #86
• 🎨 Admin for client side navigations #88
• 🎨 Add prefetch to all links and prevent scroll in pagination #87
• 🎨 Fix context not updated on prop change #90
• 🎨 Preserve client components in the DOM #89
• 🎨 WP Directives plugin - Stress testing in real sites #91 (closed because it was finished)
• Handle CDATA nodes #115
• WP Directives Plugin: Require Gutenberg plugin to avoid a fatal error #119
• Treat nodeType 7 like comments #121
• Ignore ref attr while generating virtual nodes #122
• Limit the hydration to block when client-side navigations are deactivated #124
• Fix wp-class and introduce the evaluate function #127
• Switch to the deepsignal package #128
• Make wp-context inheritable and extensible #139
• Create constants file for wp- prefixes #142
• Serialize store in PHP #147
• Handle missing class attribute inside wp-class #149
• Add wp-show directive attribute #156
• Add client-side navigation support for wp-ignore directive #163
• wp-bind improvements and negation in runtime #213
• 🎨 Switch toVdom from array iteration to createTreeWalker #103
• Fetch scripts in the <head> on client-side navigations #164
• Add server side negation operator #214
• Add a useSignalEffect implementation that behaves like useEffect #226

In progress

• Tracking Issue: Server-side rendering of directives #120

Next

• Merge new SSR state on client-side navigation #154
• Merge new SSR context on client-side navigation #155
• Automatically detect if a block is using directives #126
• Add lazy hydration techniques: idle and view #75
• Router: cancel navigation when another starts #192
• Remove directive tags (components) from the proposal #152

Decisions that need to be made

• Find a better name for wpx() (needed for the announcement blog post)
  • Rename wp_store to something else #136
• Remove directive tags (components) from the proposal #152 (needed for the announcement blog post)
• Decide on whether to follow the HTML spec or not (needed for the announcement blog post)
  • Should we follow the HTML specification to the letter? #132
• Decide the name of the client-side navigation meta tag.
• Find a way to use Preact's JSX pragma in the view.js files with backward compatibility.
• Decide whether "interactive: true" should be optional or not in the block.json.
• Decide how to use namespaces in the store #138 (needed for the announcement blog post)
• Decide the name of the npm package, like @wordpress/interactivity. #146
• Figure out how the store will work in static blocks: it won't.
• Figure out how we can pass objects to wp-context instead of a stringified JSON (in PHP and JS).
• Decide if wp-bind:value should be bidirectional in inputs.
• Find names for the full/partial/isolated hydration types.
• Decide if we should use client-side transitions or client-side navigation: we'll use client-side navigation from now on
• Figure out how to use context inside the derived state: we'll use selectors
• Decide on whether to use components or not: we won't
• Decide on the name of this repo. Something like interactivity-api-proposal. (needed for the announcement blog post)
• Is registering the block.json in the server a requirement?
• Is a single top-level node a requirement?
• What should be the HTML structure returned when wp-show is false? #159
• Decide how to name the DOM element that is passed down to the references (right now it's called ref)
• Decide if we want to expose some parts of the router and/or other configuration in the store #160 (needed for the announcement blog post)
• Decide what pattern we should use for "multiple render path" directives like wp-error-boundary or wp-suspense
• Decide if we need to name wp-html with a word the warns about its risks, like wp-dangerous-html

Experiments

• Experiment: Client-side navigation of the Query Loop block using directives gutenberg#44034
• Experiment: Client side navigations in the Product Query block woocommerce/woocommerce-blocks#7187
• Experiment: Replicate Navigation block using directives gutenberg#44509
• https://github.com/woocommerce/woocommerce-blocks/issues/8219
• Experiment: use the Interactivity API to do client-side form submissions gutenberg#49305
• Experiment: Add lightbox to Image block using directives gutenberg#49621

[luisherranz]

I've opened the main-wp-directives-plugin branch with a basic skeleton of a plugin, including a basic webpack configuration and enqueuing of the runtime/vendor scripts.

[luisherranz]

I've added some basic tasks to the OP to get the client-side navigations working, which is our first task.

These two experiments contain much of the required code:

• Experiment: Client-side navigation of the Query Loop block using directives gutenberg#44034
• Experiment: Client side navigations in the Product Query block woocommerce/woocommerce-blocks#7187

We should rename wp-client-transition to wp-link.

[SantosGuillamot]

I have created a Pull Request to "Add the wp-link to all the relative links on the page". It is still a draft, but I opened it to keep the discussion about that specific task there.

• 🎨 Add wp-link attribute to all links #81

[luisherranz]

I've created a pull request to add the basic vdom + directives functionality.

• 🎨 Add basic functionality #82

I'll now create another one for the router + wp-link.

[luisherranz]

I've created the pull request to add the router and the wp-link directive.

• 🎨 Add basic router and wp link directive #83

[luisherranz]

I've created another pull request to change the toVdom logic to test removing the comment nodes and preserving the script's children:

• 🎨 Remove comments and preserve scripts #84

[DAreRodz]

I'll be working on adding page transitions to the client-side navigations using the Shared Element Transition API. I'll share here a link to the PR soon.

[luisherranz]

I've created a PR to add support for CSS loading during client-side navigations:

• 🎨 Support CSS in client-side navigations #85

[luisherranz]

I've opened a PR to add a basic opt-in mechanism based on a custom meta tag:

• 🎨 Add meta tag to opt-in to client-side navigations #86

[SantosGuillamot]

I've opened a PR to add prefetch to all links and prevent scrolling in the pagination:

• 🎨 Add prefetch to all links and prevent scroll in pagination #87

While doing that, we realized that the HTML of the parent blocks contains the children, so we were parsing the HTML multiple times. For that, we change the filters to only trigger for the Query Loop and the Template Parts until we figure out a better solution.

[luisherranz]

Another PR to add an admin page with a checkbox to toggle client-side navigations (for testing purposes only):

• 🎨 Admin for client side navigations #88

[luisherranz]

I did a couple of bug fixes that we noticed while working on this demo:

• 🎨 Fix context not updated on prop change #90
• 🎨 Preserve client components in the DOM #89

[luisherranz]

I've opened an issue to talk about limiting the hydration surface when the site doesn't support client-side navigations:

• Limit the hydration of the Directives Hydration when the site doesn't support client-side navigations #93

[luisherranz]

@yscik opened an issue to talk about how to avoid using strings to define the directives in JSX.

• Proposal: A JSX layer for directives #94

@SantosGuillamot and I did a PR to show how server-side rendering in PHP could look like using an HTML parser.

• 🎨 Server-side rendering of wp-show in PHP #100

[luisherranz]

I closed the build-time SSR in PHP proof of concept because @ockham and @dmsnell have started working on a new run-time version based on the WP_HTML_Tag_Processor, which is much more promising.

• 🎨 Server-side rendering of wp-show in PHP #100

[luisherranz]

I have created a PR to start using createTreeWalker. I'm not going to be able to dedicate time to it in the next few days, so if anyone wants to finish it, no problem 🙂

• 🎨 Switch toVdom from array iteration to createTreeWalker #103

[SantosGuillamot]

I have created a PR to handle the CDATA nodes based on @DAreRodz proposal.

• Handle CDATA nodes #115

[luisherranz]

Latest work related to this:

• Experiment with WP_HTML_Tag_Processor #118
• WP Directives Plugin: Require Gutenberg plugin to avoid a fatal error #119
• Treat nodeType 7 like comments #121
• Ignore ref attr while generating virtual nodes #122

[luisherranz]

I've started working on the limit hydration issue:

• Issue: Limit the hydration of the Directives Hydration when the site doesn't support client-side navigations #93
• PR: Limit the hydration to block when client-side navigations are deactivated #124

[luisherranz]

The PR is ready for review:

• Limit the hydration to block when client-side navigations are deactivated #124

[luisherranz]

I forgot to mention here these two PRs, sorry!

• Fix wp-class and introduce the evaluate function #127
• Switch to the deepsignal package #128

I've also updated the opening post 🙂

[SantosGuillamot]

I've started a pull request to Add wp-show directive attribute. Right now, it only exists the wp-show directive tag (component).

• Add wp-show directive attribute #156

I've added it to the opening post (In Progress). Please let me know if it should be in any other place.

[bernhardreiter]

• Add SSR for the ones that need it - In progress \

This is led by @bernhardreiter and @dmsnell.

You've probably wanted to mention somebody else with a similar name.

[luisherranz]

Oh my. Yes, that was @ockham, sorry!

[SantosGuillamot]

I've opened an issue to discuss What should be the HTML structure returned when wp-show is false?

• What should be the HTML structure returned when wp-show is false? #159

[michalczaplinski]

I've opened an issue to discuss if we want to expose parts of the router (or other API internals) in the store:

• Decide if we want to expose some parts of the router and/or other configuration in the store #160

[dmsnell]

I'll repeat it here because I think it will be important.

Decide on whether to use wp- or data-wp-

If we can avoid using the wp- prefix we'll have much better opportunity to avoid needless performance hits in content without directives. This isn't about data-wp- vs. wp- but rather something like wp- vs. wpx-.

It'd be extremely advantageous to be able to perform this quick check and bail all directive processing.

function process_directives( $html ) {
	// Some posts will have `wpx-` without having directives,
	// But no posts will have directives without having `wpx-`.
	if ( false === strpos( $html, 'wpx-' ) ) {
		return $html;
	}
}

Looking for wp- conflates with all sorts of Gutenberg prefixes otherwise.

[luisherranz]

A small update:

• Michal opened a PR to add temporary support for fetching new scripts in client-side navigation:
  • Fetch scripts in the <head> on client-side navigations #164
• We decided on whether to use components or not: we won't
  • Remove directive tags (components) from the proposal #152
• David opened a PR to add support for client-side navigation to wp-ignore
  • Add client-side navigation support for wp-ignore directive #163

[DAreRodz]

I've merged the PR that makes wp-ignore work on client-side navigations.

• Add client-side navigation support for wp-ignore directive #163

Same with this other PR, which refactors the e2e tests a bit to prevent fetch failures during client-side navigations.

• Refactor e2e tests and add goToFile fixture #167

[SantosGuillamot]

I have started a pull request to add the wp-text directive to stop using wp-bind:children in the current examples.

• Add wp-text directive #173

[luisherranz]

I've opened a couple of issues, one to make the hydration more resilient (and make it work with template) and the other to see how we could integrate the new View Transitions API:

• Hydrate islands inside templates #172
• Explore how to integrate the new View Transitions API #178

[luisherranz]

It's very preliminary yet, but @DAreRodz and I have started an experiment to do client-side form submissions on the Comments Form block:

• Experiment: use the Interactivity API to do client-side form submissions gutenberg#49305

[luisherranz]

Added this to the list, mentioned by @tomjn here:

• Router: cancel navigation when another starts #192

[luisherranz]

Another issue related to the router:

• Router: keep favicon when doing client-side navigation #194

[michalczaplinski]

I've reopened

• Add a basic product category block woocommerce/woocommerce-blocks#136

because it became clear that wp_store is not the right final name. It would be amazing if we could decide before publishing the blog post introducing the Interactivity API because having a bad name is easy for people to nitpick.

Realistically, we might need more time, though 🙂

[luisherranz]

We finished the basic functionality of the Comments Form submission experiment:

• Experiment: use the Interactivity API to do client-side form submissions gutenberg#49305 (comment)

[luisherranz]

@artemiomorales started this experiment of a lightbox for images, similar to the one in Medium:

• Experiment: Add lightbox to Image block using directives gutenberg#49621

[luisherranz]

I've added support for the ! operator: "!state.boolean"

• wp-bind improvements and negation in runtime #213
• Add server side negation operator #214

I've also improved the logic of data-wp-bind and added some e2e tests.

[luisherranz]

I finally merged the createTreeWalker version:

• 🎨 Switch toVdom from array iteration to createTreeWalker #103

@DAreRodz and I have also started working on a branch to simplify the runtime so we can start testing it with core blocks:

• Tracking Issue - Interactivity API runtime for core blocks gutenberg#49868

[DAreRodz]

I haven't opened a PR yet, but I just started working on sorting directives by priority. I'll update this comment with the PR link soon.

[luisherranz]

We also merged this fix:

• Add a useSignalEffect implementation that behaves like useEffect #226

[luisherranz]

I'm going to close this issue as part of the migration to the Gutenberg repository.

This is the current Tracking Issue on Gutenberg. Please refer to it from now on.