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