guide: Add a user-facing web-sys section

guide/src/web-sys/cargo-features.md

@@ -0,0 +1,15 @@
+# Cargo Features in `web-sys`
+
+To keep `web-sys` building as fast as possible, there is a cargo feature for
+every type defined in `web-sys`. To access that type, you must enable its
+feature. To access a method, you must enable the feature for its `self` type and
+the features for each of its argument types. In the [API documentation][], every
+method lists the features that are required to enable it.
+
+For example, [the `WebGlRenderingContext::compile_shader` function][compile_shader] requires these features:
+
+* `WebGlRenderingContext`, because that is the method's `self` type
+* `WebGlShader`, because it takes an argument of that type
+
+[API documentation]: https://rustwasm.github.io/wasm-bindgen/api/web_sys
+[compile_shader]: https://rustwasm.github.io/wasm-bindgen/api/web_sys/struct.WebGlRenderingContext.html#method.compile_shader

guide/src/web-sys/examples/2d-canvas.md

@@ -0,0 +1,29 @@
+# 2D Canvas
+
+Drawing a smiley face with the 2D canvas API. This is a port of part of [this
+MDN
+tutorial](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Drawing_shapes#Moving_the_pen)
+to `web-sys`.
+
+[See the full source at
+`wasm-bindgen/examples/canvas`.](https://github.com/rustwasm/wasm-bindgen/tree/master/examples/canvas)
+
+![A smiley face](./2d-canvas.png)
+
+## `Cargo.toml`
+
+The `Cargo.toml` enables features necessary to query the DOM and work with 2D
+canvas.
+
+```toml
+{{#include ../../../../examples/canvas/Cargo.toml}}
+```
+
+## `src/lib.rs`
+
+Gets the `<canvas>` element, creates a 2D rendering context, and draws the
+smiley face.
+
+```rust
+{{#include ../../../../examples/canvas/src/lib.rs}}
+```

guide/src/web-sys/examples/fetch.md

@@ -0,0 +1,23 @@
+# The `fetch` API
+
+This example uses the `fetch` API to make an HTTP request to the GitHub API and
+then parses the resulting JSON.
+
+[See the full source at
+`wasm-bindgen/examples/fetch`.](https://github.com/rustwasm/wasm-bindgen/tree/master/examples/fetch)
+
+## `Cargo.toml`
+
+The `Cargo.toml` enables a number of features related to the `fetch` API and
+types used: `Headers`, `Request`, etc. It also enables `wasm-bindgen`'s `serde`
+support.
+
+```toml
+{{#include ../../../../examples/fetch/Cargo.toml}}
+```
+
+## `src/lib.rs`
+
+```rust
+{{#include ../../../../examples/fetch/src/lib.rs}}
+```

guide/src/web-sys/examples/index.md

@@ -0,0 +1,3 @@
+# Examples of using `web-sys`
+
+This subsection contains examples of using the `web-sys` crate.

guide/src/web-sys/examples/web-audio.md

@@ -0,0 +1,36 @@
+# WebAudio
+
+This example creates an [FM
+oscillator](https://en.wikipedia.org/wiki/Frequency_modulation_synthesis) using
+the [WebAudio
+API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API) and
+`web-sys`.
+
+[See the full source at
+`wasm-bindgen/examples/webaudio`.](https://github.com/rustwasm/wasm-bindgen/tree/master/examples/webaudio)
+
+## `Cargo.toml`
+
+The `Cargo.toml` enables the types needed to use the relevant bits of the
+WebAudio API.
+
+```toml
+{{#include ../../../../examples/webaudio/Cargo.toml}}
+```
+
+## `src/lib.rs`
+
+The Rust code implements the FM oscillator.
+
+```rust
+{{#include ../../../../examples/webaudio/src/lib.rs}}
+```
+
+## `index.js`
+
+A small bit of JavaScript glues the rust module to input widgets and translates
+events into calls into wasm code.
+
+```js
+{{#include ../../../../examples/webaudio/index.js}}
+```

guide/src/web-sys/function-overloads.md

@@ -0,0 +1,20 @@
+# Function Overloads
+
+Many Web APIs are overloaded to take different types of arguments or to skip
+arguments completely. `web-sys` contains multiple bindings for these functions
+that each specialize to a particular overload and set of argument types.
+
+For example, [the `fetch` API][mdn-fetch] can be given a URL string, or a
+`Request` object, and it might also optionally be given a `RequestInit` options
+object. Therefore, we end up with these `web-sys` functions that all bind to the
+`window.fetch` function:
+
+* [`Window::fetch_with_str`](https://rustwasm.github.io/wasm-bindgen/api/web_sys/struct.Window.html#method.fetch_with_str)
+* [`Window::fetch_with_request`](https://rustwasm.github.io/wasm-bindgen/api/web_sys/struct.Window.html#method.fetch_with_request)
+* [`Window::fetch_with_str_and_init`](https://rustwasm.github.io/wasm-bindgen/api/web_sys/str_and_inituct.Window.html#method.fetch_with_str_and_init)
+* [`Window::fetch_with_request_and_init`](https://rustwasm.github.io/wasm-bindgen/api/web_sys/struct.Window.html#method.fetch_with_request_and_init)
+
+Note that different overloads can use different interfaces, and therefore can
+require different sets of cargo features to be enabled.
+
+[mdn-fetch]: https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch

guide/src/web-sys/index.md

@@ -0,0 +1,23 @@
+# The `web-sys` Crate
+
+The `web-sys` crate provides raw `wasm-bindgen` imports for all of the Web's
+APIs. This includes:
+
+* `window.fetch`
+* `Node.prototype.appendChild`
+* WebGL
+* WebAudio
+* and many more!
+
+It's sort of like the `libc` crate, but for the Web.
+
+It does *not* include the JavaScript APIs that are guaranteed to exist in all
+standards-compliant ECMAScript environments, such as `Array`, `Date`, and
+`eval`. Bindings for these APIs can be found in [the `js-sys` crate][js-sys].
+
+## API Documentation
+
+[**Read the `web-sys` API documentation here!**][api]
+
+[api]: https://rustwasm.github.io/wasm-bindgen/api/web_sys/
+[js-sys]: https://crates.io/crates/js-sys

guide/src/web-sys/type-translations.md

@@ -0,0 +1,22 @@
+# Type Translations in `web-sys`
+
+Most of the types specified in [WebIDL (the interface definition language for
+all Web APIs)][webidl] have relatively straightforward translations into
+`web-sys`, but it's worth calling out a few in particular:
+
+* `BufferSource` and `ArrayBufferView` - these two types show up in a number of
+  APIs that generally deal with a buffer of bytes. We bind them in `web-sys`
+  with two different types, `js_sys::Object` and `&mut [u8]`. Using
+  `js_sys::Object` allows passing in arbitrary JS values which represent a view
+  of bytes (like any typed array object), and `&mut [u8]` allows using a raw
+  slice in Rust. Unfortunately we must pessimistically assume that JS will
+  modify all slices as we don't currently have information of whether they're
+  modified or not.
+
+* Callbacks are all represented as `js_sys::Function`. This means that all
+  callbacks going through `web-sys` are a raw JS value. You can work with this
+  by either juggling actual `js_sys::Function` instances or you can create a
+  `Closure<FnMut(...)>`, extract the underlying `JsValue` with `as_ref`, and
+  then use `JsCast::unchecked_ref` to convert it to a `js_sys::Function`.
+
+[webidl]: https://heycam.github.io/webidl/

guide/src/web-sys/using-web-sys.md

@@ -0,0 +1,61 @@
+# Using `web-sys`
+
+## Add `web-sys` as a dependency to your `Cargo.toml`
+
+***Note:** `web-sys` is not available on crates.io yet, so you'll need to depend
+on the git version of it, and of `wasm-bindgen`:*
+
+```toml
+[dependencies]
+wasm-bindgen = { git = "https://github.com/rustwasm/wasm-bindgen" }
+web-sys = {
+  git = "https://github.com/rustwasm/wasm-bindgen",
+  features = [
+  ]
+}
+```
+
+## Enable the cargo features for the APIs you're using
+
+To keep build times super speedy, [`web-sys` gates each Web interface behind a
+cargo feature](./cargo-features.html). Find the type or method you want to use
+in the [API documentation][api]; it will list the features that must be enabled
+to access that API.
+
+For example, if we're looking for [the `window.resizeTo`
+function][js-resize-to], we would [search for `resizeTo` in the API
+documentation][search-resize-to]. We would find [the
+`web_sys::Window::resize_to` function][rust-resize-to], which requires the
+`Window` feature. To get access to that function, we enable the `Window` feature
+in `Cargo.toml`:
+
+```toml
+web-sys = {
+  git = "https://github.com/rustwasm/wasm-bindgen",
+  features = [
+    "Window",
+  ]
+}
+```
+
+## Call the method!
+
+```rust
+extern crate web_sys;
+extern crate wasm_bindgen;
+
+use wasm_bindgen::prelude::*;
+use web_sys::Window;
+
+#[wasm_bindgen]
+pub fn make_the_window_small() {
+    // Resize the window to 500px by 500px.
+    Window::resize_to(500, 500)
+        .expect("could not resize the window");
+}
+```
+
+[api]: https://rustwasm.github.io/wasm-bindgen/api/web_sys/
+[js-resize-to]: https://developer.mozilla.org/en-US/docs/Web/API/window/resizeTo
+[search-resize-to]: https://rustwasm.github.io/wasm-bindgen/api/web_sys/?search=resizeTo
+[rust-resize-to]: https://rustwasm.github.io/wasm-bindgen/api/web_sys/struct.Window.html#method.resize_to