docs: add guide for supporting pop-out windows

[Fevol]

This is a preliminary PR for adding a brief guide on how to use proper APIs to support pop-out windows. The guide itself is mainly based on the blog post written by Licat when the feature was first added.

Some of the notable changes include:

• Remove all 'we' references
• Reworded some sentences for clarity

---

This PR is ready to merge, but it might be useful to add some pointers for proper API usage. When searching around for existing plugins making use of these API's, I was wondering what the actual 'proper' usage is of them.

Adding listeners on window/document

I found some plugins that makes use of the following construction (e.g. found in a View construction):

activeWindow.addEventListener('click', callback);

However, I feel like this isn't entirely correct. Aside from the fact that some of the plugin never even unregister the listener, there are also some other problems:

• If the vault is being initialised, and the view being exists in a pop-out window, then the listener would be added to the wrong window
• If the view gets dragged back into another window, the listener is never moved

// Bad: the event listener isn't necessarily added to the same window as the view
window.addEventListener('click', callback);

// Bad: the event listener isn't added to the same window as the view
activeWindow.addEventListener('click', callback);

// Bad: but if the view is moved back, the event listener is lost
this.containerEl.win.addEventListener('click', callback);

// Good: remove and re-add the event listener based on the window it is in
this.containerEl.win.addEventListener('click', callback);
this.containerEl.onWindowMigrate((win) => {
  win.addEventListener('click', callback);
});

Is it possible to get the previous window in onWindowMigrate? That way, the event listener can be correctly removed.

Guideline for correct window/document access

This question is more about devising a good guideline for when to use which document/window accessor API:

1. element.doc/element.win or event.doc/event.win: Use this if you need something to happen on the correct window/document
2. activeDocument/activeWindow: Use this for timers like setTimeout
3. document/window: Use this for everything else
   (Updated based on Licat's comments)