Make DOM utilities work in nested browsing contexts

[acusti]

Fixes #156. In the discussion in that issue, @spicyj wrote:

If this is causing a problem in some Facebook project using fbjs, feel free to send a pull request.

I’ve seen a couple issues that I’m hoping can qualify, including:

facebook/react#427
facebookarchive/draft-js#527

I can also say that I am working with a team on an editor app that would benefit greatly from having React, Draft.js, and fbjs all work seamlessly across iframes. When building a sophisticated editor of some kind, the use case of rendering from a single parent browsing context into a separate nested browsing context, treating it as a sandboxed rendering target that can publish UI events, is a really compelling one.

About the PR: We used eslint’s no-undef rule with a config that didn’t include the browser env to get a list of all files that use browser globals directly. We then went through each instance and adapted them to support use across nested browsing contexts where necessary.

Here’s a list of the files that use browser globals that we didn’t modify, along with an explanation of why. The only file we didn’t change where it could actually matter is getViewportDimensions, so I’ll start with that one:

fbjs/src/core/dom/getViewportDimensions.js

Uses global document and window extensively. Could be easily refactored to take an optional document argument, like getDocumentScrollElement, but I also couldn’t find it being used anywhere in fbjs or in React, so didn’t know if it was worth it or desired. Please let me know if I should implement that change.

fbjs/src/__forks__/isEventSupported.js
fbjs/src/core/ExecutionEnvironment.js
fbjs/src/dom/translateDOMPositionXY.js

Feature (or UA) detection against the global window / document objects

fbjs/src/core/createNodesFromMarkup.js
fbjs/src/core/getMarkupWrap.js
fbjs/src/core/getVendorPrefixedName.js

Uses document.createElement(), no nested browsing context issues

fbjs/src/core/dom/getDocumentScrollElement.js

Uses global document as fallback default (just like the changes we made in this PR for getActiveElement.js)

fbjs/src/core/dom/getStyleProperty.js

Uses window.getComputedStyle, which seems to work fine across nested browsing contexts

There are also some polyfill / feature detections for fetch, requestAnimationFrame, Performance, ES2015 Map/Set that use globals, but I figured it wouldn’t be helpful to list those out.

[acusti]

I tried to add tests where there were any existing test files I could add to, which turned out to only be packages/fbjs/src/core/dom/getActiveElement.js and packages/fbjs/src/core/dom/isNode.js. The getActiveElement test case was easy, but the isNode one proved trickier. Here’s the test I wanted to add:

  it('should accept nodes from different document contexts', function() {
    var iframe = document.createElement('iframe');
    document.body.appendChild(iframe);
    try {
      expect(isNode(iframe.contentDocument.body)).toBe(true);
    } finally {
      document.body.removeChild(iframe);
    }
  });

However, I realized when verifying it that the assertions always passed, even without our changes (i.e. with isNode relying on the global Node constructor). This led to the realization that jsdom has only a single DOM implementation (set of DOM constructors) that it shares across any browsing contexts, which I documented in detail, so I don’t think there is currently a way to capture this behavior in a test case using jsdom, but instead would require an actual browser (and not Firefox, because it has surprising instanceof behavior across nested browsing contexts).

I also wasn’t sure about using flow. Tried to keep files in the style they were already written in, but I could of course add real flow annotations to, for example, packages/fbjs/src/core/dom/getActiveElement.js.

[acusti]

I created a demo of a simple use case to illustrate the utility of this PR. I then duplicated the demo and have one using the current react and react-dom builds and one using built versions of those files made from the React branch I made that uses these changes with the changes in this branch npm linked into it.

Without the changes in this branch + the React PR: http://codepen.io/acusti/pen/kkBpWA?editors=0011
With the changes in this branch + the React PR: http://codepen.io/acusti/pen/rrpKYZ?editors=0011

[acusti]

Here’s another version of the demo, but with a different implementation that illustrates the benefits of these changes slightly more effectively:

Without the changes in this branch + the React PR: http://codepen.io/acusti/pen/EgQxJG?editors=0011
With the changes in this branch + the React PR: http://codepen.io/acusti/pen/qaxBby?editors=0011

[sophiebits]

I think this looks mostly good, thanks.

[sophiebits]

Can we do ownerDocument.defaultView || ownerDocument.parentWindow for IE8 compat?

[sophiebits]

When is it appropriate to fall back to document here?

[acusti]

Never, good point. WIll update

[acusti]

I updated with those changes, thanks @spicyj

[sophiebits]

This will throw if doc is null, won't it?

[acusti]

I’m thinking doc can’t be null. It definitely passes the isNode tests.

If object is null, doc is document
If object is not null but object.ownerDocument is null, doc becomes object, which wasn’t null
If object is not null and object.ownerDocument is not null, it won’t throw

[sophiebits]

Oh, my mistake. I missed the || object. This seems good.

[acusti]

@spicyj Do you have an opinion about getViewportDimensions? Should I modify the get* functions to take an optional doc argument?

[sophiebits]

Eh, let's leave it for now.

[conartist6]

Look at the commit and original rationale for #59. In getActiveElement.js. Either we should remove the check for undefined document or we should ensure that we do not reference document before we check to make sure its type is not undefined.

[sophiebits]

@conartist6 Good catch. Do you mind sending a PR fixing this and a diff internally?

[conartist6]

Will do.

[conartist6]

I think the fix is actually slightly more complicated because this function's return type in flow (which I'm adding and is why I'm looking) should be DOMElement (not DOMElement?). Calling in doesn't make sense if you know there's no document.

The original puller's issue should be fixed in react then, which can be trivially modified to guard the calls with if (ExecutionEnvironment.canUseDOM) { since we already know that react considers the result to be nullable.

[sophiebits]

I don't believe we call getActiveElement in React except when doing client-side rendering.

[acusti]

I don’t believe React ever calls getActiveElement outside of SelectEventPlugin and ReactInputSelection which are definitely only used in client-side rendering.

I only kept the if (typeof doc === 'undefined') { check because it was the pre-existing behavior and I didn’t know where else that utility is used. Seems like removing that and changing the return value to DOMElement is a good idea and should work fine.

[acusti]

@spicyj I have a PR (well, 2 of them, but they’re just alternative approaches to the same feature/fix) to React that depend on these changes: facebook/react#7936 and facebook/react#7866

Don’t know when this PR will be released, and I’m not sure how to coordinate this all. There’s also an updated version of jsdom that is now being required in master at jest, but there’s no new release available there either, and that would be nice to have in React for my PR because it would mean removing hacky jsdom workarounds from the tests I added. And then there’s the fact that those are all required for a PR I’m preparing to draft.js to make it independent of the global window / document objects (so it will work when rendered into an iframe), but I haven’t even opened that one yet.

Is there anything I can do to help with the coordination of all this? I’m particularly curious if there’s anything I can do to help with the React PR; one of my new tests is currently failing on Travis, but that’s because it depends on this PR, and I think it could still be worthwhile for someone to review it. Thanks for any info or recommendations you can provide! I truly and deeply appreciate the extraordinary effort and commitment you and the rest of the React ecosystem-related team at Facebook have been making for the open source stewardship of all these projects.

[sophiebits]

We're just really behind and I haven't had time to look. I don't think there's anything else we need from you right now. Sorry for the wait.

[conartist6]

@acusti These changes are merged, what are you waiting on?

[acusti]

@conartist6 Can’t be installed until a new release of fbjs gets published to npm. In order to use it in our app, we needed to create a repo with just the built files of the fbjs package and an updated package.json and point to that repo in our package.json ("fbjs": "Brandcast/fbjs-built#97b8e54",).

[conartist6]

Ah, ok.

[ExE-Boss]

With jsdom/jsdom#2691 merged and jsdom/jsdom#1453 finally fixed, the isNode(…) test can finally be implemented:

it('should accept nodes from different document contexts', () => {
	const iframe = document.createElement('iframe');
	document.body.appendChild(iframe);
	try {
		expect(isNode(iframe.contentDocument.body)).toBe(true);
	} finally {
		document.body.removeChild(iframe);
	}
});