v2: add dom package

[dmitshur]

This change implements the starting point of a new v2 major version
of the dom package.

It is now implemented on top of the syscall/js API, which is supported
by Go WebAssembly and GopherJS (as of version 1.12-2). The design goal
has been to stay as close as possible to v1 API to make the transition
easier to make. The only changes that were done were out of necessity:

• All struct fields with js:"foo" tags have been replaced with
  equivalent methods
• Underlying() returns js.Value instead of *js.Object
• AddEventListener() returns js.Func instead of func(*js.Object)

There is a remaining TODO in window.RequestAnimationFrame method
to make it so that canceling the callback via CancelAnimationFrame
makes it so the js.Func wrapper's Release method is called. Arranging
this is difficult (it requires either having an internal map and sync
primitive for tracking js.Func by IDs, or changing the return value of
the RequestAnimationFrame method from int to something where the
js.Func and its Release method can be accessed easily.

The current implementation is functional but may end up using more
memory in some situations. It's not blocking for the initial alpha
release, so it remains a TODO for now.

This implementation was based on work done by @yml in
Pull Request #59.

Fixes #57.

/cc @neelance @hajimehoshi @myitcv

[dominikh]

• All of the attribute setters are missing.
• Can we document that v2 is an alpha, and that there might still be breaking changes? We'll have breaking changes due to callbacks.
• Now that v2 has a go.mod, does v1 need a go.mod, too?

As for the issue with releasing callbacks: Please don't introduce a map to map integers to handlers. Instead, we should return an opaque type that contains all the necessary information to remove a callback and release the function. Yes, that deviates more from the v1 API, but the benefits hugely outweigh that.

[dmitshur]

All of the attribute setters are missing.

Thanks for catching that huge and embarrassing blunder. :) We do need to add methods for setting attributes too.

Can we document that v2 is an alpha, and that there might still be breaking changes? We'll have breaking changes due to callbacks.

Yes, we should make that more clear and visible. We reserve the right to make changes to v2, and the likelihood of that happening is inversely proportional to its age.

I don't plan to make any release version tags for now, so the final v2.0.0 version is still far away. It will be pseudo-versions only for now.

Now that v2 has a go.mod, does v1 need a go.mod, too?

As far as I know, it does not need one. Since it's missing, the go command will continue to implicitly create one that contains only a module statement, as it currently does.

(However, I've never tried this, so there's a small chance I'm wrong about this. But it's easily fixable if it turns out to be a problem.)

That said, we can certainly add one. But doing so is an action that is orthogonal to adding v2.

[myitcv]

Would it not be preferable to code generate this API?

https://gowebapi.github.io/

This was mentioned in a discussion in https://groups.google.com/d/msg/golang-nuts/v7JoKNGTsR4/F8CLi4sNBgAJ

My preference would be towards code generating from the IDL spec.

And I'd almost be tempted to direct efforts towards supporting gowebapi rather than duplicating the work here (unless I'm missing something as to how the two are different)

cc @martin-juhlin

[dmitshur]

@myitcv You made this suggestion in #59 (comment) and it was discussed briefly there. It's a very big change in direction and I think it should be a separate issue rather than a comment on a PR that implements a concrete plan.

This dom package was created in January of 2014, and it currently has 215 known importers on godoc.org (many of them are small test packages). The goal of this PR is to resolve issue #57, that is add support for Go WebAssembly in addition to GopherJS.

To implement that goal, a breaking API change must be made, which is why the import path is changing its major version to v2. But the goal is to make the API change as small as possible, so it's as easy to migrate existing Go code that imports honnef.co/go/js/dom to import honnef.co/go/js/dom/v2 instead.

My preference would be towards code generating from the IDL spec.

Using code generation and the IDL spec is a valid approach to create a Go binding for the DOM API, but that's not the approach used by this project in v1. It's not in scope for v2, which was proposed and accepted in #57 (comment). It would have to be either v3 API (that we should discuss in a separate issue), or it can happen in a different project (as is already the case, I think that's the right approach).

Users can choose which Go package they prefer to use for their needs. This PR is about adding WebAssembly support for people who want to continue to use this existing dom package and its existing API in their projects.

[myitcv]

I think it should be a separate issue rather than a comment on a PR that implements a concrete plan

I'm raising the point here in case it makes sense for us to reconsider prior to any further work, but it sounds like you have decided on the approach you'd like to follow.

[dmitshur]

@dominikh The last two comments should address all your points, PTAL.