Add shortcuts help dialog (#400)

Author: syg

css/elements.css

@@ -1212,3 +1212,44 @@ li.menu-search-result-term:before {
 .clause-attributes-tag a {
   color: #884400;
 }
+
+/* Shortcuts help dialog */
+
+#shortcuts-help {
+  position: fixed;
+  left: 5%;
+  margin: 0 auto;
+  right: 5%;
+  z-index: 10;
+  top: 10%;
+  top: calc(5vw + 5vh);
+  padding: 30px 90px;
+  max-width: 500px;
+  outline: solid 10000px rgba(255, 255, 255, 0.6);
+  border-radius: 5px;
+  border-width: 1px 1px 0 1px;
+  background-color: #ddd;
+  display: none;
+}
+
+#shortcuts-help.active {
+  display: block;
+}
+
+#shortcuts-help ul {
+  padding: 0;
+}
+
+#shortcuts-help li {
+  display: flex;
+  justify-content: space-between;
+}
+
+#shortcuts-help code {
+  padding: 3px 10px;
+  border-radius: 3px;
+  border-width: 1px 1px 0 1px;
+  border-color: #bbb;
+  background-color: #eee;
+  box-shadow: inset 0 -1px 0 #ccc;
+}

js/menu.js

@@ -47,7 +47,7 @@ Search.prototype.loadBiblio = function () {
 };
 
 Search.prototype.documentKeydown = function (e) {
-  if (e.keyCode === 191) {
+  if (e.key === '/') {
     e.preventDefault();
     e.stopPropagation();
     this.triggerSearch();
@@ -973,7 +973,7 @@ function doShortcut(e) {
   if (name === 'textarea' || name === 'input' || name === 'select' || target.isContentEditable) {
     return;
   }
-  if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) {
+  if (e.altKey || e.ctrlKey || e.metaKey) {
     return;
   }
   if (e.key === 'm' && usesMultipage) {
@@ -995,6 +995,8 @@ function doShortcut(e) {
     }
   } else if (e.key === 'u') {
     document.documentElement.classList.toggle('show-ao-annotations');
+  } else if (e.key === '?') {
+    document.getElementById('shortcuts-help').classList.toggle('active');
   }
 }
 
@@ -1010,8 +1012,11 @@ function init() {
   document.addEventListener(
     'keydown',
     debounce(e => {
-      if (e.code === 'Escape' && Toolbox.active) {
-        Toolbox.deactivate();
+      if (e.code === 'Escape') {
+        if (Toolbox.active) {
+          Toolbox.deactivate();
+        }
+        document.getElementById('shortcuts-help').classList.remove('active');
       }
     })
   );

src/Spec.ts

@@ -519,18 +519,22 @@ export default class Spec {
     this.setCharset();
     const wrapper = this.buildSpecWrapper();
 
-    let tocEles: HTMLElement[] = [];
+    let commonEles: HTMLElement[] = [];
     let tocJs = '';
     if (this.opts.toc) {
       this.log('Building table of contents...');
 
       if (this.opts.oldToc) {
         new Toc(this).build();
       } else {
-        ({ js: tocJs, eles: tocEles } = makeMenu(this));
+        ({ js: tocJs, eles: commonEles } = makeMenu(this));
       }
     }
-    for (const ele of tocEles) {
+
+    this.log('Building shortcuts help dialog...');
+    commonEles.push(this.buildShortcutsHelp());
+
+    for (const ele of commonEles) {
       this.doc.body.insertBefore(ele, this.doc.body.firstChild);
     }
 
@@ -539,7 +543,7 @@ export default class Spec {
     const jsSha = sha(jsContents);
 
     if (this.opts.multipage) {
-      await this.buildMultipage(wrapper, tocEles, jsSha);
+      await this.buildMultipage(wrapper, commonEles, jsSha);
     }
 
     await this.buildAssets(jsContents, jsSha);
@@ -731,7 +735,7 @@ export default class Spec {
     return null;
   }
 
-  private async buildMultipage(wrapper: Element, tocEles: Element[], jsSha: string) {
+  private async buildMultipage(wrapper: Element, commonEles: Element[], jsSha: string) {
     let stillIntro = true;
     const introEles = [];
     const sections: { name: string; eles: Element[] }[] = [];
@@ -864,9 +868,9 @@ ${await utils.readFile(path.join(__dirname, '../js/multipage.js'))}
     for (const { name, eles } of sections) {
       this.log(`Generating section ${name}...`);
       const headClone = head.cloneNode(true) as HTMLHeadElement;
-      const tocClone = tocEles.map(e => e.cloneNode(true));
+      const commonClone = commonEles.map(e => e.cloneNode(true));
       const clones = eles.map(e => e.cloneNode(true));
-      const allClones = [headClone, ...tocClone, ...clones];
+      const allClones = [headClone, ...commonClone, ...clones];
       // @ts-ignore
       const links = allClones.flatMap(e => [...e.querySelectorAll('a,link')]);
       for (const link of links) {
@@ -919,10 +923,10 @@ ${await utils.readFile(path.join(__dirname, '../js/multipage.js'))}
       }
 
       // @ts-ignore
-      const tocHTML = tocClone.map(e => e.outerHTML).join('\n');
+      const commonHTML = commonClone.map(e => e.outerHTML).join('\n');
       // @ts-ignore
       const clonesHTML = clones.map(e => e.outerHTML).join('\n');
-      const content = `<!doctype html>${htmlEle}\n${headClone.outerHTML}\n<body>${tocHTML}<div id='spec-container'>${clonesHTML}</div></body>`;
+      const content = `<!doctype html>${htmlEle}\n${headClone.outerHTML}\n<body>${commonHTML}<div id='spec-container'>${clonesHTML}</div></body>`;
 
       this.generatedFiles.set(path.join(this.opts.outfile!, `multipage/${name}.html`), content);
     }
@@ -1027,6 +1031,19 @@ ${await utils.readFile(path.join(__dirname, '../js/multipage.js'))}
     return wrapper;
   }
 
+  private buildShortcutsHelp() {
+    const shortcutsHelp = this.doc.createElement('div');
+    shortcutsHelp.setAttribute('id', 'shortcuts-help');
+    shortcutsHelp.innerHTML = `
+<ul>
+  <li><span>Toggle shortcuts help</span><code>?</code></li>
+  <li><span>Toggle "can call user code" annotations</span><code>u</code></li>
+${this.opts.multipage ? `<li><span>Navigate to/from multipage</span><code>m</code></li>` : ''}
+  <li><span>Jump to search box</span><code>/</code></li>
+</ul>`;
+    return shortcutsHelp;
+  }
+
   private processMetadata() {
     const block = this.doc.querySelector('pre.metadata');
 

test/baselines/generated-reference/algorithm-replacements.html

@@ -1,5 +1,11 @@
 <!doctype html>
-<head><meta charset="utf-8"></head><body><div id="spec-container">
+<head><meta charset="utf-8"></head><body><div id="shortcuts-help">
+<ul>
+  <li><span>Toggle shortcuts help</span><code>?</code></li>
+  <li><span>Toggle "can call user code" annotations</span><code>u</code></li>
+
+  <li><span>Jump to search box</span><code>/</code></li>
+</ul></div><div id="spec-container">
 
 <emu-clause id="test">
   <h1><span class="secnum">1</span> Title</h1>

test/baselines/generated-reference/algorithms.html

@@ -1,5 +1,11 @@
 <!doctype html>
-<head><meta charset="utf-8"></head><body><div id="spec-container">
+<head><meta charset="utf-8"></head><body><div id="shortcuts-help">
+<ul>
+  <li><span>Toggle shortcuts help</span><code>?</code></li>
+  <li><span>Toggle "can call user code" annotations</span><code>u</code></li>
+
+  <li><span>Jump to search box</span><code>/</code></li>
+</ul></div><div id="spec-container">
 <emu-biblio href="./algorithmsBiblio.json"></emu-biblio>
 <emu-alg><ol><li>Can call <emu-xref href="#sec-algorithm-conventions-abstract-operations"><a href="https://tc39.es/ecma262/#sec-algorithm-conventions-abstract-operations">abstract operations</a></emu-xref> in this spec: <emu-xref aoid="Internal" id="_ref_0"><a href="#sec-internal">Internal</a></emu-xref>();</li><li>Can call <emu-xref href="#sec-algorithm-conventions-abstract-operations"><a href="https://tc39.es/ecma262/#sec-algorithm-conventions-abstract-operations">abstract operations</a></emu-xref> in ES6: <emu-xref aoid="ReturnIfAbrupt" id="_ref_1"><a href="https://tc39.es/ecma262/#sec-returnifabrupt">ReturnIfAbrupt</a></emu-xref>(<var>completion</var>);</li><li>Can call <emu-xref href="#sec-algorithm-conventions-abstract-operations"><a href="https://tc39.es/ecma262/#sec-algorithm-conventions-abstract-operations">abstract operations</a></emu-xref> in a biblio file: <emu-xref aoid="Biblio"><a href="http://example.com/fooSite.html#sec-biblio">Biblio</a></emu-xref>();</li><li>Unfound <emu-xref href="#sec-algorithm-conventions-abstract-operations"><a href="https://tc39.es/ecma262/#sec-algorithm-conventions-abstract-operations">abstract operations</a></emu-xref> just don't link: Unfound();</li><li>Can prefix with !&nbsp;and ?.<ol><li>Let <var>foo</var> be ?&nbsp;<emu-xref aoid="Internal" id="_ref_2"><a href="#sec-internal">Internal</a></emu-xref>();</li><li>Set <var>foo</var> to !&nbsp;<emu-xref aoid="Internal" id="_ref_3"><a href="#sec-internal">Internal</a></emu-xref>();</li><li>Set <var>foo</var> to !&nbsp;SDO of <var>operation</var>.</li><li>Set <var>foo</var> to !&nbsp;<var>operation</var>.[[MOP]]().</li></ol></li></ol></emu-alg>
 

test/baselines/generated-reference/autolinking.html

@@ -1,5 +1,11 @@
 <!doctype html>
-<head><meta charset="utf-8"></head><body><div id="spec-container">
+<head><meta charset="utf-8"></head><body><div id="shortcuts-help">
+<ul>
+  <li><span>Toggle shortcuts help</span><code>?</code></li>
+  <li><span>Toggle "can call user code" annotations</span><code>u</code></li>
+
+  <li><span>Jump to search box</span><code>/</code></li>
+</ul></div><div id="spec-container">
 <emu-clause id="sec-foo">
   <h1><span class="secnum">1</span> Autolinking</h1>
   <p>Type, type, <emu-xref aoid="Type" id="_ref_0"><a href="https://tc39.es/ecma262/#sec-ecmascript-data-types-and-values">Type</a></emu-xref>(), type()</p>

test/baselines/generated-reference/boilerplate-address.html

@@ -1,5 +1,11 @@
 <!doctype html>
-<head><meta charset="utf-8"><title>test title!</title></head><body><div id="spec-container"><h1 class="title">test title!</h1>
+<head><meta charset="utf-8"><title>test title!</title></head><body><div id="shortcuts-help">
+<ul>
+  <li><span>Toggle shortcuts help</span><code>?</code></li>
+  <li><span>Toggle "can call user code" annotations</span><code>u</code></li>
+
+  <li><span>Jump to search box</span><code>/</code></li>
+</ul></div><div id="spec-container"><h1 class="title">test title!</h1>
 
 <emu-annex id="sec-copyright-and-software-license">
       <h1><span class="secnum">A</span> Copyright &amp; Software License</h1>

test/baselines/generated-reference/boilerplate-all.html

@@ -1,5 +1,11 @@
 <!doctype html>
-<head><meta charset="utf-8"><title>test title!</title></head><body><div id="spec-container"><h1 class="title">test title!</h1>
+<head><meta charset="utf-8"><title>test title!</title></head><body><div id="shortcuts-help">
+<ul>
+  <li><span>Toggle shortcuts help</span><code>?</code></li>
+  <li><span>Toggle "can call user code" annotations</span><code>u</code></li>
+
+  <li><span>Jump to search box</span><code>/</code></li>
+</ul></div><div id="spec-container"><h1 class="title">test title!</h1>
 
 <emu-annex id="sec-copyright-and-software-license">
       <h1><span class="secnum">A</span> Copyright &amp; Software License</h1>

test/baselines/generated-reference/boilerplate-copyright.html

@@ -1,5 +1,11 @@
 <!doctype html>
-<head><meta charset="utf-8"><title>test title!</title></head><body><div id="spec-container"><h1 class="title">test title!</h1>
+<head><meta charset="utf-8"><title>test title!</title></head><body><div id="shortcuts-help">
+<ul>
+  <li><span>Toggle shortcuts help</span><code>?</code></li>
+  <li><span>Toggle "can call user code" annotations</span><code>u</code></li>
+
+  <li><span>Jump to search box</span><code>/</code></li>
+</ul></div><div id="spec-container"><h1 class="title">test title!</h1>
 
 <emu-annex id="sec-copyright-and-software-license">
       <h1><span class="secnum">A</span> Copyright &amp; Software License</h1>

test/baselines/generated-reference/boilerplate-license.html

@@ -1,5 +1,11 @@
 <!doctype html>
-<head><meta charset="utf-8"><title>test title!</title></head><body><div id="spec-container"><h1 class="title">test title!</h1>
+<head><meta charset="utf-8"><title>test title!</title></head><body><div id="shortcuts-help">
+<ul>
+  <li><span>Toggle shortcuts help</span><code>?</code></li>
+  <li><span>Toggle "can call user code" annotations</span><code>u</code></li>
+
+  <li><span>Jump to search box</span><code>/</code></li>
+</ul></div><div id="spec-container"><h1 class="title">test title!</h1>
 
 <emu-annex id="sec-copyright-and-software-license">
       <h1><span class="secnum">A</span> Copyright &amp; Software License</h1>

test/baselines/generated-reference/charset-absent.html

@@ -1,3 +1,9 @@
 <!doctype html>
-<head><meta charset="utf-8"></head><body><div id="spec-container">
+<head><meta charset="utf-8"></head><body><div id="shortcuts-help">
+<ul>
+  <li><span>Toggle shortcuts help</span><code>?</code></li>
+  <li><span>Toggle "can call user code" annotations</span><code>u</code></li>
+
+  <li><span>Jump to search box</span><code>/</code></li>
+</ul></div><div id="spec-container">
 </div></body>

test/baselines/generated-reference/charset-present.html

@@ -1,5 +1,11 @@
 <!doctype html>
 <head><meta charset="utf-8">
-</head><body><div id="spec-container">
+</head><body><div id="shortcuts-help">
+<ul>
+  <li><span>Toggle shortcuts help</span><code>?</code></li>
+  <li><span>Toggle "can call user code" annotations</span><code>u</code></li>
+
+  <li><span>Jump to search box</span><code>/</code></li>
+</ul></div><div id="spec-container">
 
 </div></body>

test/baselines/generated-reference/clauses.html

@@ -1,5 +1,11 @@
 <!doctype html>
-<head><meta charset="utf-8"></head><body class=" oldtoc"><div id="spec-container">
+<head><meta charset="utf-8"></head><body class=" oldtoc"><div id="shortcuts-help">
+<ul>
+  <li><span>Toggle shortcuts help</span><code>?</code></li>
+  <li><span>Toggle "can call user code" annotations</span><code>u</code></li>
+
+  <li><span>Jump to search box</span><code>/</code></li>
+</ul></div><div id="spec-container">
 <div><h2>Table of Contents</h2><ol class="toc"><li><a href="#sec-intro" title="Intro">Intro</a><ol class="toc"><li><a href="#sec-intro2" title="Sub Intro">Sub Intro</a></li></ol></li><li><a href="#sec-clause" title="Clause Foo(a, b)"><span class="secnum">1</span> Clause Foo(<var>a</var>, <var>b</var>)</a><ol class="toc"><li><a href="#Foo" title="Sub Clause"><span class="secnum">1.1</span> Sub Clause</a></li></ol></li><li><a href="#sec-annex" title="Annex"><span class="secnum">A</span> Annex</a><ol class="toc"><li><a href="#sec-annex2" title="Sub-annex"><span class="secnum">A.1</span> Sub-annex</a></li></ol></li></ol></div><emu-intro id="sec-intro">
   <h1>Intro</h1>
   <emu-intro id="sec-intro2">

test/baselines/generated-reference/code.html

@@ -1,5 +1,11 @@
 <!doctype html>
-<head><meta charset="utf-8"></head><body><div id="spec-container">
+<head><meta charset="utf-8"></head><body><div id="shortcuts-help">
+<ul>
+  <li><span>Toggle shortcuts help</span><code>?</code></li>
+  <li><span>Toggle "can call user code" annotations</span><code>u</code></li>
+
+  <li><span>Jump to search box</span><code>/</code></li>
+</ul></div><div id="spec-container">
 <link rel="stylesheet" href="css/elements.css">
 <emu-clause id="foo">
   <h1><span class="secnum">1</span> Test Clause</h1>

test/baselines/generated-reference/copyright.html

@@ -1,5 +1,11 @@
 <!doctype html>
-<head><meta charset="utf-8"><title>test title!</title></head><body><div id="spec-container"><h1 class="version">Draft 1 / September 26, 2014</h1><h1 class="title">test title!</h1>
+<head><meta charset="utf-8"><title>test title!</title></head><body><div id="shortcuts-help">
+<ul>
+  <li><span>Toggle shortcuts help</span><code>?</code></li>
+  <li><span>Toggle "can call user code" annotations</span><code>u</code></li>
+
+  <li><span>Jump to search box</span><code>/</code></li>
+</ul></div><div id="spec-container"><h1 class="version">Draft 1 / September 26, 2014</h1><h1 class="title">test title!</h1>
 <emu-clause id="sec-clause">
   <h1><span class="secnum">1</span> Test Clause</h1>
 </emu-clause><emu-annex id="sec-copyright-and-software-license">

test/baselines/generated-reference/date.html

@@ -1,5 +1,11 @@
 <!doctype html>
-<head><meta charset="utf-8"><title>test title!</title></head><body><div id="spec-container"><h1 class="title">test title!</h1>
+<head><meta charset="utf-8"><title>test title!</title></head><body><div id="shortcuts-help">
+<ul>
+  <li><span>Toggle shortcuts help</span><code>?</code></li>
+  <li><span>Toggle "can call user code" annotations</span><code>u</code></li>
+
+  <li><span>Jump to search box</span><code>/</code></li>
+</ul></div><div id="spec-container"><h1 class="title">test title!</h1>
 
 <p>Some body content</p>
 

test/baselines/generated-reference/dfn.html

@@ -1,5 +1,11 @@
 <!doctype html>
-<head><meta charset="utf-8"></head><body><div id="spec-container">
+<head><meta charset="utf-8"></head><body><div id="shortcuts-help">
+<ul>
+  <li><span>Toggle shortcuts help</span><code>?</code></li>
+  <li><span>Toggle "can call user code" annotations</span><code>u</code></li>
+
+  <li><span>Jump to search box</span><code>/</code></li>
+</ul></div><div id="spec-container">
 <emu-intro id="sec-intro">
   <h1>Intro</h1>
   <p>Forward references to <emu-xref href="#sec-dfn" id="_ref_0"><a href="#sec-dfn">dfn</a></emu-xref> work.</p>

test/baselines/generated-reference/duplicate-ids.html

@@ -1,5 +1,11 @@
 <!doctype html>
-<head><meta charset="utf-8"></head><body><div id="spec-container">
+<head><meta charset="utf-8"></head><body><div id="shortcuts-help">
+<ul>
+  <li><span>Toggle shortcuts help</span><code>?</code></li>
+  <li><span>Toggle "can call user code" annotations</span><code>u</code></li>
+
+  <li><span>Jump to search box</span><code>/</code></li>
+</ul></div><div id="spec-container">
 <emu-clause id="sec-a">
   <h1><span class="secnum">1</span> A</h1>
   <emu-clause id="sec-a">

test/baselines/generated-reference/duplicate-productions.html

@@ -1,5 +1,11 @@
 <!doctype html>
-<head><meta charset="utf-8"></head><body><div id="spec-container">
+<head><meta charset="utf-8"></head><body><div id="shortcuts-help">
+<ul>
+  <li><span>Toggle shortcuts help</span><code>?</code></li>
+  <li><span>Toggle "can call user code" annotations</span><code>u</code></li>
+
+  <li><span>Jump to search box</span><code>/</code></li>
+</ul></div><div id="spec-container">
 <emu-production name="Prod"><emu-nt><a href="#prod-Prod">Prod</a></emu-nt> <emu-geq>:</emu-geq> </emu-production>
 <emu-grammar><emu-production name="GMD" type="lexical">
     <emu-nt><a href="#prod-GMD">GMD</a></emu-nt> <emu-geq>::</emu-geq> <emu-rhs a="opbw7lol">

test/baselines/generated-reference/effect-user-code.html

@@ -1,5 +1,11 @@
 <!doctype html>
-<head><meta charset="utf-8"></head><body><div id="spec-container">
+<head><meta charset="utf-8"></head><body><div id="shortcuts-help">
+<ul>
+  <li><span>Toggle shortcuts help</span><code>?</code></li>
+  <li><span>Toggle "can call user code" annotations</span><code>u</code></li>
+
+  <li><span>Jump to search box</span><code>/</code></li>
+</ul></div><div id="spec-container">
 
 <emu-clause id="sec-user-code" type="abstract operation" aoid="UserCode">
   <h1><span class="secnum">1</span> UserCode ( )</h1>