Improved documentation and fixed search reset

.env

@@ -24,8 +24,6 @@
 if [ ! -d venv ]; then
   echo "Setting up virtual environment"
   virtualenv venv
-  echo "Installing dependencies"
-  pip install -r requirements.txt
 fi
 
 # Activate virtual environment

.stylelintrc

@@ -185,7 +185,7 @@
     "selector-class-pattern": "^[a-z0-9]+(-[a-z0-9]+)*(__[a-z]+)?(--[a-z]+)?$",
     "selector-descendant-combinator-no-non-space": null,
     "string-quotes": "double",
-    "unit-whitelist": ["px", "em", "deg", "s", "%", "mm", "vh", "dppx"],
+    "unit-whitelist": ["px", "em", "deg", "ms", "%", "mm", "vh", "dppx"],
     "value-keyword-case": "lower",
     "value-no-vendor-prefix": true
   }

material/assets/manifest.json

@@ -1,10 +1,10 @@
 {
-  "assets/javascripts/bundle.js": "assets/javascripts/bundle.af5dd3a5.min.js",
-  "assets/javascripts/bundle.js.map": "assets/javascripts/bundle.af5dd3a5.min.js.map",
+  "assets/javascripts/bundle.js": "assets/javascripts/bundle.525b1d98.min.js",
+  "assets/javascripts/bundle.js.map": "assets/javascripts/bundle.525b1d98.min.js.map",
   "assets/javascripts/worker/packer.js": "assets/javascripts/worker/packer.c14659e8.min.js",
   "assets/javascripts/worker/packer.js.map": "assets/javascripts/worker/packer.c14659e8.min.js.map",
-  "assets/javascripts/worker/search.js": "assets/javascripts/worker/search.3144ce89.min.js",
-  "assets/javascripts/worker/search.js.map": "assets/javascripts/worker/search.3144ce89.min.js.map",
+  "assets/javascripts/worker/search.js": "assets/javascripts/worker/search.0a5433f7.min.js",
+  "assets/javascripts/worker/search.js.map": "assets/javascripts/worker/search.0a5433f7.min.js.map",
   "assets/stylesheets/app-palette.scss": "assets/stylesheets/app-palette.3f90c815.min.css",
-  "assets/stylesheets/app.scss": "assets/stylesheets/app.0ee2cfd0.min.css"
+  "assets/stylesheets/app.scss": "assets/stylesheets/app.83fc891a.min.css"
 }

material/base.html

@@ -43,7 +43,7 @@
       {% endif %}
     {% endblock %}
     {% block styles %}
-      <link rel="stylesheet" href="{{ 'assets/stylesheets/app.0ee2cfd0.min.css' | url }}">
+      <link rel="stylesheet" href="{{ 'assets/stylesheets/app.83fc891a.min.css' | url }}">
       {% if palette.primary or palette.accent %}
         <link rel="stylesheet" href="{{ 'assets/stylesheets/app-palette.3f90c815.min.css' | url }}">
       {% endif %}
@@ -190,7 +190,7 @@
       {% endblock %}
     </div>
     {% block scripts %}
-      <script src="{{ 'assets/javascripts/bundle.af5dd3a5.min.js' | url }}"></script>
+      <script src="{{ 'assets/javascripts/bundle.525b1d98.min.js' | url }}"></script>
       <script id="__lang" type="application/json">
         {%- set translations = {} -%}
         {%- for key in [
@@ -209,7 +209,7 @@
         {%- endfor -%}
         {{ translations | tojson }}
       </script>
-      <script>app=initialize({base:"{{ base_url }}",worker:{search:"{{ 'assets/javascripts/worker/search.3144ce89.min.js' | url }}",packer:"{{ 'assets/javascripts/worker/packer.c14659e8.min.js' | url }}"}})</script>
+      <script>app=initialize({base:"{{ base_url }}",worker:{search:"{{ 'assets/javascripts/worker/search.0a5433f7.min.js' | url }}",packer:"{{ 'assets/javascripts/worker/packer.c14659e8.min.js' | url }}"}})</script>
       {% for path in config["extra_javascript"] %}
         <script src="{{ path | url }}"></script>
       {% endfor %}

src/assets/javascripts/components/_/index.ts

@@ -82,7 +82,7 @@ let components$: Observable<ComponentMap>
  * Watch components with given names
  *
  * This function returns an observable that will maintain bindings to the given
- * components in-between document switches and update the document in-place.
+ * components in-between document switches and update the components in-place.
  *
  * @param names - Component names
  * @param options - Options

src/assets/javascripts/components/navigation/index.ts

@@ -40,14 +40,14 @@ import {
  * ------------------------------------------------------------------------- */
 
 /**
- * Navigation below screen breakpoint
+ * Navigation for [screen -]
  */
 export interface NavigationBelowScreen {
   layer: NavigationLayer               /* Active layer */
 }
 
 /**
- * Navigation above screen breakpoint
+ * Navigation for [screen +]
  */
 export interface NavigationAboveScreen {
   sidebar: Sidebar                     /* Sidebar */
@@ -94,7 +94,7 @@ export function mountNavigation(
       .pipe(
         switchMap(screen => {
 
-          /* Mount navigation above screen breakpoint */
+          /* [screen +]: Mount navigation in sidebar */
           if (screen) {
             return watchSidebar(el, { main$, viewport$ })
               .pipe(
@@ -102,7 +102,7 @@ export function mountNavigation(
                 map(sidebar => ({ sidebar }))
               )
 
-          /* Mount navigation below screen breakpoint */
+          /* [screen -]: Mount navigation in drawer */
           } else {
             const els = getElements("nav", el)
             return watchNavigationLayer(els)

src/assets/javascripts/components/search/index.ts

@@ -79,19 +79,19 @@ export function mountSearch(
   return pipe(
     switchMap(() => {
 
-      /* Mount search query */
-      const query$ = useComponent<HTMLInputElement>("search-query")
-        .pipe(
-          mountSearchQuery(handler),
-          shareReplay(1)
-        )
-
       /* Mount search reset */
       const reset$ = useComponent<HTMLInputElement>("search-reset")
         .pipe(
           mountSearchReset()
         )
 
+      /* Mount search query */
+      const query$ = useComponent<HTMLInputElement>("search-query")
+        .pipe(
+          mountSearchQuery(handler, { reset$ }),
+          shareReplay(1)
+        )
+
       /* Mount search result */
       const result$ = useComponent("search-result")
         .pipe(

src/assets/javascripts/components/search/query/index.ts

@@ -63,7 +63,6 @@ export function mountSearchQuery(
       /* Subscribe worker to search query */
       query$
         .pipe(
-          distinctUntilKeyChanged("value"),
           map<SearchQuery, SearchQueryMessage>(({ value }) => ({
             type: SearchMessageType.QUERY,
             data: value

src/assets/javascripts/components/toc/index.ts

@@ -47,12 +47,12 @@ import {
  * ------------------------------------------------------------------------- */
 
 /**
- * Table of contents below tablet breakpoint
+ * Table of contents for [tablet -]
  */
 export interface TableOfContentsBelowTablet {} // tslint:disable-line
 
 /**
- * Table of contents above tablet breakpoint
+ * Table of contents for [tablet +]
  */
 export interface TableOfContentsAboveTablet {
   sidebar: Sidebar                     /* Sidebar */
@@ -101,7 +101,7 @@ export function mountTableOfContents(
       .pipe(
         switchMap(tablet => {
 
-          /* Mount table of contents above tablet breakpoint */
+          /* [tablet +]: Mount table of contents in sidebar */
           if (tablet) {
             const els = getElements<HTMLAnchorElement>(".md-nav__link", el)
 
@@ -123,7 +123,7 @@ export function mountTableOfContents(
                 map(([sidebar, anchors]) => ({ sidebar, anchors }))
               )
 
-          /* Mount table of contents below tablet breakpoint */
+          /* [tablet -]: Unmount table of contents */
           } else {
             return of({})
           }

src/assets/javascripts/integrations/search/_/index.ts

@@ -102,7 +102,7 @@ export class SearchIndex {
    *
    * A mapping of URLs (including hash fragments) to the actual articles and
    * sections of the documentation. The search document mapping must be created
-   * regardless of whether the index was prebuilt or not, as lunr itself will
+   * regardless of whether the index was prebuilt or not, as `lunr` itself will
    * only store the actual index.
    */
   protected documents: SearchDocumentMap
@@ -113,7 +113,7 @@ export class SearchIndex {
   protected highlight: SearchHighlightFactoryFn
 
   /**
-   * The lunr search index
+   * The `lunr` search index
    */
   protected index: lunr.Index
 

src/assets/javascripts/observables/search/query/index.ts

@@ -20,12 +20,14 @@
  * IN THE SOFTWARE.
  */
 
-import { Observable, combineLatest, fromEvent } from "rxjs"
+import { Observable, combineLatest, fromEvent, merge } from "rxjs"
 import {
+  delay,
   distinctUntilChanged,
   map,
   shareReplay,
-  startWith
+  startWith,
+  tap
 } from "rxjs/operators"
 
 import { watchElementFocus } from "../../agent"
@@ -61,7 +63,7 @@ interface WatchOptions {
  * Default transformation function
  *
  * Rogue control characters are filtered before handing the query to the
- * search index, as lunr will throw otherwise.
+ * search index, as `lunr` will throw otherwise.
  *
  * @param value - Query value
  *
@@ -81,6 +83,9 @@ function defaultTransform(value: string): string {
 /**
  * Watch search query
  *
+ * Note that the focus event which triggers re-reading the current query value
+ * is delayed by `1ms` so the input's empty state is allowed to propagate.
+ *
  * @param el - Search query element
  * @param options - Options
  *
@@ -91,7 +96,10 @@ export function watchSearchQuery(
 ): Observable<SearchQuery> {
 
   /* Intercept keyboard events */
-  const value$ = fromEvent(el, "keyup")
+  const value$ = merge(
+    fromEvent(el, "keyup"),
+    fromEvent(el, "focus").pipe(delay(1))
+  )
     .pipe(
       map(() => transform(el.value)),
       startWith(transform(el.value)),

src/assets/javascripts/observables/search/result/index.ts

@@ -57,7 +57,7 @@ import { SearchQuery } from "../query"
  */
 interface PaintOptions {
   query$: Observable<SearchQuery>     /* Search query observable */
-  fetch$: Observable<boolean>         /* Search trigger observable */
+  fetch$: Observable<boolean>         /* Result fetch observable */
 }
 
 /* ----------------------------------------------------------------------------
@@ -67,6 +67,10 @@ interface PaintOptions {
 /**
  * Paint search results from source observable
  *
+ * This function will perform a lazy rendering of the search results, depending
+ * on the vertical offset of the search result container. When the scroll offset
+ * reaches the bottom of the element, more results are fetched and rendered.
+ *
  * @param el - Search result element
  * @param options - Options
  *

src/assets/javascripts/patches/details/index.ts

@@ -50,6 +50,9 @@ interface MountOptions {
 /**
  * Patch all `details` elements
  *
+ * This function will ensure that all `details` tags are opened prior to
+ * printing, so the whole content of the page is included.
+ *
  * @param options - Options
  *
  * @return Details elements observable

src/assets/javascripts/patches/table/index.ts

@@ -44,6 +44,9 @@ interface MountOptions {
 /**
  * Patch all `table` elements
  *
+ * This function will re-render all tables by wrapping them to improve overflow
+ * scrolling on smaller screen sizes.
+ *
  * @param options - Options
  *
  * @return Table elements observable

src/assets/javascripts/templates/clipboard/index.tsx

@@ -38,7 +38,7 @@ const css = {
  * ------------------------------------------------------------------------- */
 
 /**
- * Render clipboard
+ * Render a 'copy-to-clipboard' button
  *
  * @param id - Unique identifier
  *

src/assets/javascripts/templates/table/index.tsx

@@ -39,7 +39,7 @@ const css = {
  * ------------------------------------------------------------------------- */
 
 /**
- * Render a table wrapper
+ * Render a table inside a wrapper to improve scrolling on mobile
  *
  * @param table - Table element
  *

src/assets/javascripts/utilities/rxjs/_/index.ts

@@ -28,7 +28,7 @@ import { map } from "rxjs/operators"
  * ------------------------------------------------------------------------- */
 
 /**
- * Invert boolean value of source observable
+ * Invert the value of a toggle observable
  *
  * @param toggle$ - Toggle observable
  *

src/assets/javascripts/utilities/string/index.ts

@@ -59,6 +59,11 @@ export function translate(key: string, value?: string): string {
 /**
  * Truncate a string after the given number of characters
  *
+ * This is not a very reasonable approach, since the summaries kind of suck.
+ * It would be better to create something more intelligent, highlighting the
+ * search occurrences and making a better summary out of it, but this note was
+ * written three years ago, so who knows if we'll ever fix it.
+ *
  * @param value - Value to be truncated
  * @param n - Number of characters
  *

src/assets/javascripts/workers/packer/_/index.ts

@@ -33,6 +33,13 @@ import { PackerMessage } from "../message"
 /**
  * Setup packer web worker
  *
+ * This function will create a web worker that helps in packing and unpacking
+ * strings using an LZ-based algorithm, namely `lz-string`. Its main purpose is
+ * to compress the search index before storing it in local storage, so it can
+ * be retrieved and imported to minimize the time necessary to setup search.
+ *
+ * @see https://bit.ly/2Q1ArhU - LZ-String documentation
+ *
  * @param url - Worker url
  *
  * @return Worker handler

src/assets/javascripts/workers/search/_/index.ts

@@ -113,7 +113,7 @@ export function setupSearchWorker(
           pluck("response")
         )
 
-  /* Send index to search worker */
+  /* Send index to worker */
   index$
     .pipe<SearchSetupMessage>(
       map(data => ({

src/assets/javascripts/workers/search/main/index.ts

@@ -40,6 +40,9 @@ let index: SearchIndex
 /**
  * Setup multi-language support through `lunr-languages`
  *
+ * This function will automatically import the stemmers necessary to process
+ * the languages which were given through the search index configuration.
+ *
  * @param config - Search index configuration
  */
 function setupLunrLanguages(config: SearchIndexConfig): void {
@@ -58,7 +61,7 @@ function setupLunrLanguages(config: SearchIndexConfig): void {
 
   /* Load scripts synchronously */
   if (scripts.length)
-    importScripts(
+    self.importScripts(
       `${base}/min/lunr.stemmer.support.min.js`,
       ...scripts
     )

src/assets/stylesheets/layout/_base.scss

@@ -77,14 +77,7 @@ body {
 
     // Lock body to viewport height (e.g. in search mode)
     &[data-md-state="lock"] {
-      height: 100%;
-      min-height: auto;
-      overflow: hidden;
-
-      // Hide container on iOS, or the body will not be locked correctly
-      .ios & .md-container {
-        display: none;
-      }
+      position: fixed;
     }
   }
 }

tsconfig.json

@@ -5,7 +5,6 @@
     "declaration": false,
     "declarationMap": false,
     "downlevelIteration": true,
-    "importHelpers": true,
     "jsx": "react",
     "jsxFactory": "h",
     "lib": [

webpack.config.ts

@@ -61,6 +61,7 @@ function config(args: Configuration): Configuration {
                 experimentalWatchApi: true,
                 transpileOnly: true,
                 compilerOptions: {
+                  importHelpers: true,
                   module: "esnext",
                   removeComments: false
                 }