Reorganize the org.scalajs.dom namespace into something saner

[lihaoyi]

• The raw "everything goes" namespace is now org.scalajs.dom.raw
• org.scalajs.dom.{css, html, idb, svg, webgl} namespaces contain un-prefixed versions of the things that start with their prefix. The Element suffix has also been dropped where possible
• org.scalajs.dom.extensions has been renamed to org.scalajs.dom.ext
• org.scalajs.dom itself contains all things in org.scalajs.dom.raw that aren't in any of the un-prefixed namespaces

Overall, this should accomplish a few things:

• Massively clean up org.scalajs.dom.*, since we've moved ~270 names into proper namespaces
• Make dealing with these names much easier, e.g. now dom.HTMLTableCellElement is just html.TableCell
• Make a clear separation between "all un-modified dom facades" and "re-organized nice-to-use dom facades", so hopefully there won't be any confusion over things missing or where things should go
• Reasonable backwards compat just by changing imports: org.scalajs.dom -> org.scalajs.dom.raw and things should keep working

Some Caveats:

• The mapping isn't quite perfect: we still have svg.RectElement instead of just svg.Rect, sinct svg.Rect is taken by something else
• You don't get doc-dropdown in IntelliJ because of the aliases. I assume this is something we can bug the IntelliJ people to fix since it affects lots of other things (e.g. the std lib) and not just Scala.js

[sjrd]

I would recommend @inline def Rule = raw.CSSRule for these cases instead.
val could cause problems if you have more than one in one namespace. If one exists and you access it, but another doesn't in that browser, you'll get a boom, just because the object is entirely initialized to give you the val you asked for, but in doing so it also tries to fetch all the other vals in that object.

[sjrd]

An alternative is lazy val, but it has a footprint in terms of generated code. The @inline def completely disappears after optimizations.

[sjrd]

What about things like Event. It's not in any of the namespaces, but I don't want to write raw.Event. It doesn't feel right.

[lihaoyi]

Those guys get aliased in dom.*, inside the package object

[sjrd]

That was a ScalaDoc link. It should be kept.

[benjaminjackman]

Maybe at a top level this should be called org.scalajs.webapi or (just org.scalajs.web) since it superceeds the DOM. And then all of the methods here could be implemented:
https://developer.mozilla.org/en-US/docs/Web/API

Then a standard namespacing rule could be created, items that have prefixes are lumped together under a package so
org.scalajs.web.html.* holds all the html elements in the shortened form.

Further moz items could be put under a moz namespace as an optional extension, but still coherenet with this.

One last issue is what constitutes a namespace vs what doesn't should all the audio elements be placed into a namespace (e.g. audio.Buffer, audio.Node, audio.Param) or left at the top level (e.g. AudioBuffer AudioNode AudioParam) etc?

[lihaoyi]

Yeah, I'm open to renaming things.

One last issue is what constitutes a namespace vs what doesn't should all the audio elements be placed into a namespace (e.g. audio.Buffer, audio.Node, audio.Param) or left at the top level (e.g. AudioBuffer AudioNode AudioParam) etc?

Maybe =P I just grabbed things which looked like there was a lot of prefix-repetition and pulled them out. We could pull out more.

[benjaminjackman]

There is some implicit namespacing (hierarchies) on this page:
https://developer.mozilla.org/en-US/docs/WebAPI

Basically it breaks down to be all the WebApis, then the DOM get's it's own section (it's near the bottom of the page)

So in that case you would have things like:
org.scalajs.web.dom.html
org.scalajs.web.dom.svg
org.scalajs.web.dom.Event
org.scalajs.web.dom.Document

org.scalajs.web.hardware.

//indexed db
org.scalajs.web.idb.
--or--
org.scalajs.web.data.idb.
org.scalajs.web.data.contacts.

[benjaminjackman]

I'm just throwing this out there because if we are breaking stuff and getting the house in order for 1.0 anyhow it might be worth considering how to logically wrap all of the WebAPIs into a coherent hierarchy along with the dom stuff.

Do you guys know/remember how does typescript structures this? I think it's one big flat namespace but I haven't used it for a while.

[lihaoyi]

Typescript dumps them all in one huge namespace; when I generated these it was in that form, and I had to split it up into "Html.scala" "Css.scala" etc. manually

[benjaminjackman]

Yeah I found it: https://github.com/c9/typescript/blob/master/bin/lib.d.ts

You're right It's a big blob. I was hoping maybe they had done something clever...

However it as a total aside it reminded of some nice features they have over there, take for example an anchor element:

 getElementsByTagName(name: "a"): NodeListOf<HTMLAnchorElement>; createElement(tagName: "a"): HTMLAnchorElement;

Pretty documentation

interface HTMLAnchorElement extends HTMLElement, MSDataBindingExtensions { /**  * Sets or retrieves the relationship between the object and the destination of the link.  */ rel: string; /**  * Contains the protocol of the URL.  */ protocol: string; /**  * Sets or retrieves the substring of the href property that follows the question mark.  */ search: string; /**  * Sets or retrieves the coordinates of the object.  */ coords: string; /**  * Contains the hostname of a URL.  */ hostname: string; /**  * Contains the pathname of the URL.  */ pathname: string; Methods: string; /**  * Sets or retrieves the window or frame at which to target content.  */ target: string; protocolLong: string; /**  * Sets or retrieves a destination URL or an anchor point.  */ href: string; /**  * Sets or retrieves the shape of the object.  */ name: string; /**  * Sets or retrieves the character set used to encode the object.  */ charset: string; /**  * Sets or retrieves the language code of the object.  */ hreflang: string; /**  * Sets or retrieves the port number associated with a URL.  */ port: string; /**  * Contains the hostname and port values of the URL.  */ host: string; /**  * Contains the anchor portion of the URL including the hash sign (#).  */ hash: string; nameProp: string; urn: string; /**  * Sets or retrieves the relationship between the object and the destination of the link.  */ rev: string; /**  * Sets or retrieves the shape of the object.  */ shape: string; type: string; mimeType: string; /**   * Returns a string representation of an object.  */ toString(): string; }

And then they can call new on their facades

declare var HTMLAnchorElement: { prototype: HTMLAnchorElement; new (): HTMLAnchorElement; }

[sjrd]

You can't have custom vals in a js.GlobalScope. That's an accessor to raw JS stuff. The Travis build reports tons of warnings about this.

[lihaoyi]

Fixed everything brought up. Also took the opportunity to arrange all the aliases nicely in alphabetical order. Not going to bother doing the same with the original definitions unless someone has an automated tool to do so

[lihaoyi]

@benjaminjackman if you feel that the various other faux-namespaces are a pain feel free to send a PR to break them out. There are lots of things that can be broken out (e.g. svg.fe.*) but not gonna do so for now unless someone really cares

[sjrd]

This ScalaDoc is superfluous.

[sjrd]

Same thing about the ScalaDoc.

[lihaoyi]

Updated

[sjrd]

Useless import.

[sjrd]

That's all.

I was a bit skeptical before. But it looks nice, I think.

[lihaoyi]

Updated. @sjrd do you have a lint tool or something that finds all these for you? Could save time in future reviews =P

[sjrd]

do you have a lint tool or something that finds all these for you?

I have my eyes ^^ I'm quite pedantic about these things, so I immediately spot these things. If I had a tool, I'd run it as part of CI.

[sjrd]

You forgot this one (compiler warning told me so: https://travis-ci.org/scala-js/scala-js-dom/jobs/46440575)

[lihaoyi]

Are these going to turn into errors at some point? Or maybe I should just turn on fatal warnings...

[sjrd]

Are these going to turn into errors at some point? Or maybe I should just turn on fatal warnings...

In 1.0.0, yes. See scala-js/scala-js#1111
But you can also turn on fatal warnings, yes, good idea.

That's all. Is the plan to merge this one right away, or are we waiting for some particular event? I remember reading something along those lines but couldn't find any reference anymore.

[lihaoyi]

Good question. I was thinking to publish the current version in parallel with the new version for 0.6.0, so at least people can upgrade to 0.6.0 without being blocked on changing all their code.

On the other hand, upgrading (without modifying too much code) is easy because you just need to import the {raw => dom} and you'll be on your way. So maybe it's not a huge deal asking people to upgrade?

Merging it now and only publishing the new version for 0.6.0 would inconvenience everyone (bad) but force them to upgrade (good). WDYT?

[sjrd]

If it's just a matter of publishing, we can always publish 0.7.0 for Scala.js 0.6.0 when it comes out: checkout tag v0.7.0, edit project/build.sbt to change Scala.js' version, and republish. That's what I did for 0.6.0-M3.

[lihaoyi]

Cool, in that case I don't mind merging it now. Let's call it 0.8.0?

[sjrd]

LGTM

[sjrd]

We'll have to call it 0.8.0, yes, given how much is changed in here.