WebUI: Update styleguide

- Fix outdated references to various grit options and add some
  documentation of preprocess_if_expr and generate_grd.
- Update to recommend the class based syntax for new custom elements.

Change-Id: Ie61bf939a214dbef938340e69ed34d179cb5da66
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2853078
Reviewed-by: dpapad <dpapad@chromium.org>
Commit-Queue: Rebekah Potter <rbpotter@chromium.org>
Cr-Commit-Position: refs/heads/master@{#877184}

styleguide/web/web.md

@@ -254,20 +254,14 @@ compatibility issues are less relevant for Chrome-only code).
 
 ### URLs
 
-* Don't embed data URIs in source files. Instead, use grit's flattening.
+* Don't embed data URIs in source files. Instead, use a relative path to an icon
+  in your UI (and include this icon in the generated grd file), or use an
+  absolute URL for an icon from the shared resources at ui/webui/resources:
 
 ```css
-background-image: url(../path/to/image.svg);
+background-image: url(chrome://resources/images/path/to/image.svg);
 ```
 
-The contents of image.svg are base64-encoded and the `url()` is replaced with
-
-```css
-background-image: url(data:image/svg+xml;base64,...);
-```
-
-if `flattenhtml="true"` is specified in your .grd file.
-
 ### RTL
 
 ```css
@@ -304,7 +298,8 @@ See the [Google JavaScript Style
 Guide](https://google.github.io/styleguide/jsguide.html) as well as
 [ECMAScript Features in Chromium](es.md).
 
-* Use `$('element-id')` instead of `document.getElementById`
+* Use `$('element-id')` instead of `document.getElementById`. This function can
+  be imported from util.m.js.
 
 * Use single-quotes instead of double-quotes for all strings.
     * `clang-format` now handles this automatically.
@@ -362,9 +357,42 @@ Guide](https://google.github.io/styleguide/jsguide.html) as well as
 
 Also see the [Google Polymer Style Guide](http://go/polymer-style).
 
-* Use a consistent ordering in the “prototype” object passed to `Polymer()`:
+* Elements with UI should have their HTML in a .html file and logic in a JS file
+  with the same name. The HTML should be copied into the final JS file at build
+  time, replacing the special `{__html_template__}` sequence, using the
+  html_to_js BUILD.gn rule. For example the following will paste the contents
+  of my_app.html into the final generated JS file:
+```
+  html_to_js('web_components') {
+    js_files = [ 'my_app.js' ]
+  }
+```
+
+* In new code, use class based syntax for custom elements. Example:
+```js
+import {html, PolymerElement} from 'chrome://resources/polymer/v3_0/polymer/polymer_bundled.m.js';
+
+class MyAppElement extends PolymerElement {
+  static get is() {
+    return 'my-app';
+  }
+
+  static get template() {
+    return html`{__html_template__}`;
+  }
+
+  static get properties() {
+    return {
+      foo: String,
+    };
+  }
+}
+```
+
+* Use a consistent ordering for common methods (or, in legacy code, the
+  parameters passed to Polymer()):
     * `is`
-    * `behaviors`
+    * `behaviors` (legacy code only)
     * `properties` (public, then private)
     * `hostAttributes`
     * `listeners`, `observers`
@@ -380,14 +408,16 @@ Also see the [Google Polymer Style Guide](http://go/polymer-style).
   duplicated in less places, i.e. `@param`).
 
 ```js
-properties: {
-  foo: {type: Number, observer: 'fooChanged_'}
-},
+static get properties() {
+  return {
+    foo: {type: Number, observer: 'fooChanged_'},
+  };
+}
 
 /** @private */
-fooChanged_: function() {
+fooChanged_() {
   this.bar = this.derive(this.foo);
-},
+}
 ```
 
 * Use native `on-click` for click events instead of `on-tap`. 'tap' is a
@@ -420,16 +450,60 @@ https://www.polymer-project.org/2.0/docs/devguide/templates#dom-if):
 ## Grit processing
 
 Grit is a tool that runs at compile time to pack resources together into
-Chromium.
+Chromium. Resources are packed from grd files. Most Chromium WebUI resources
+should be located in autogenerated grd files created by the generate_grd gn
+rule.
 
 ### Preprocessing
 
-Grit can be used to selectively include or exclude code at compile-time in web
-code.  Preprocessing is enabled by adding the `preprocess="true"` attribute
-inside of a `.grd` file on `<structure>` and `<include>` nodes.
+Sometimes it is helpful to selectively include or exclude code at compile-time.
+This is done using the preprocess_if_expr gn rule, which makes use of a subset
+of grit that reads and processes files for `<if expr>` without running the
+entire grit resource packing process.  Files that require preprocessing are
+passed to the rule as in_files. Preprocessed versions with the same names will
+be written to the specified out_folder and are listed in out_manifest, which can
+be passed to the generate_grd rule to generate entries for them in a grd file.
+
+### Example
+
+The following BUILD.gn example code uses preprocess_if_expr to preprocess any
+`<if expr>` in the final my_app.js file that is generated by the earlier
+html_to_js example. It then uses the manifest from this operation and the
+in_files option to place both the final, preprocessed file and a separate (not
+preprocessed) icon into a generated grd file using generate_grd:
+
+```
+preprocess_folder = "preprocessed"
+preprocess_manifest = "preprocessed_manifest.json"
+
+# Read file from target_gen_dir, where it will be pasted by html_to_js.
+preprocess_if_expr("preprocess") {
+  deps = [ ":web_components" ]
+  in_folder = target_gen_dir
+  in_files = [ "my_app.js" ]
+  out_folder = "$target_gen_dir/$preprocess_folder"
+  out_manifest = "$target_gen_dir/$preprocess_manifest"
+}
+
+# Put the preprocessed file as well as a separate my_icon.svg file in the grd:
+generate_grd("build_grd") {
+  input_files = [ "my_icon.svg" ]
+  input_files_base_dir = rebase_path(".", "//")
+  deps = [ ":preprocess" ]
+  manifest_files = [ "$target_gen_dir/$preprocess_manifest" ]
+  grd_prefix = [ "foo" ]
+  out_grd = "$target_gen_dir/resources.grd"
+}
+```
 
 *** aside
-Note: These preprocessor statements can live in places that surprise linters or
+Note #1:
+In a few legacy resources, preprocessing is enabled by adding the
+`preprocess="true"` attribute inside of a `.grd` file on `<structure>` and
+`<include>` nodes.
+
+Note #2:
+These preprocessor statements can live in places that surprise linters or
 formatters (for example: running clang-format on a .js file with an `<if>` in
 it).  Generally, putting these language-invalid features inside of comments
 helps alleviate problems with unexpected input.
@@ -452,30 +526,16 @@ function isWindows() {
 `<include src="[path]">` reads the file at `path` and replaces the `<include>`
 tag with the file contents of `[path]`. Don't use `<include>` in new JS code;
 [it is being removed.](https://docs.google.com/document/d/1Z18WTNv28z5FW3smNEm_GtsfVD2IL-CmmAikwjw3ryo/edit?usp=sharing#heading=h.66ycuu6hfi9n)
-Instead, use JS imports in new pages and pages that use JS modules.
+Instead, use JS imports. If there is concern about importing a large number of
+JS files, the optimize_webui build rule supports bundling pages using Rollup.
 
-Grit can read and inline resources when enabled via `flattenhtml="true"`.
+Some legacy UIs use Grit to read and inline resources via `flattenhtml="true"`.
+This option should not be used in new code; instead, use JS imports and bundling
+as needed. Icons can also be placed in an iconset, to avoid importing them
+individually.
 
 *** aside
-Note: The implementation of flattening does HTML parsing and URL detection via regular
-expressions and is not guaranteed to work in all cases.
+Note: The implementation of flattening does HTML parsing and URL detection via
+regular expressions and is not guaranteed to work in all cases. In particular,
+it does not work with any generated resources.
 ***
-
-Example:
-
-```css
-.spinner {
-  background: url(../relative/file/path/to/spinner.svg);
-}
-```
-
-Is transformed to:
-
-```css
-.spinner {
-  background: url(data:image/svg+xml;... base64-encoded content ...);
-}
-```
-
-A minification tool can be specified to Grit (like Closure compiler) to
-transform the code before it's packed into a bundle.