Improved documentation and fixed search reset

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
     )