Merge 5efb5d7 into 83c5440

assets/js/app.js

@@ -30,6 +30,8 @@ import {initialize as initVersions} from './versions'
 import {initialize as initNightMode} from './night'
 import {initialize as initMakeup} from './makeup'
 import {initialize as initKeyboardShortcuts} from './keyboard-shortcuts'
+import {initialize as initTooltips} from './tooltips/tooltips'
+import {initialize as initHintsPage} from './tooltips/hints-page'
 
 window.$ = $
 
@@ -65,5 +67,7 @@ $(() => {
   initEvents()
   initMakeup()
   initKeyboardShortcuts()
+  initTooltips()
+  initHintsPage()
   hljs.initHighlighting()
 })

assets/js/keyboard-shortcuts.js

@@ -53,7 +53,7 @@ const keyboardShortcuts = [
 // State
 // -----
 
-// Stores shortcut info to prevent multiple activations ok keyDown event
+// Stores shortcut info to prevent multiple activations on keyDown event
 let shortcutBeingPressed = null
 
 // Local Methods

assets/js/templates/tooltip-body.handlebars

@@ -0,0 +1,22 @@
+{{#if isType}}
+  <section class="docstring docstring-type">
+    {{this.hint.description}}
+  </section>
+{{else}}
+  <div class="detail-header">
+      {{#if this.isModule}}
+        <h2>{{this.hint.title}}</h2>
+      {{else}}
+        <h1 class="signature">
+          {{this.hint.title}}
+          <div class="version-info">{{this.hint.version}}</div>
+          <div class="specs">{{this.hint.signatureSpecs}}</div>
+        </h1>
+      {{/if}}
+  </div>
+  {{#if this.hint.description}}
+    <section class="docstring">
+      {{this.hint.description}}
+    </section>
+  {{/if}}
+{{/if}}

assets/js/templates/tooltip-layout.handlebars

@@ -0,0 +1,4 @@
+<div id="tooltip">
+  <div class="tooltip-body"></div>
+  <iframe class="tooltip-iframe"></iframe>
+</div>

assets/js/tooltips/hints-extraction.js

@@ -0,0 +1,38 @@
+
+// Dependencies
+// ------------
+
+/**
+ * Extracts info about a function, callback or a type defined inside a module.
+ *
+ * @param {Object} element jQuery selector pointing to a div containing relevant data
+ *
+ * @returns {Object} hint info object
+ */
+function extractFunctionHint (element) {
+  const signatureSpecs = element.find('.specs').text()
+  const title = element.find('h1').text()
+  const description = element.find('.docstring > p:first').text()
+
+  return {
+    kind: 'function',
+    title: title.trim(),
+    signatureSpecs: signatureSpecs.trim(),
+    description: description.trim()
+  }
+}
+
+function extractModuleHint (content) {
+  content.find('h1:first > *').remove()
+
+  return {
+    kind: 'module',
+    title: content.find('h1:first').text().trim(),
+    description: content.find('#moduledoc p:first').text().trim()
+  }
+}
+
+// Public Methods
+// --------------
+
+export {extractModuleHint, extractFunctionHint}

assets/js/tooltips/hints-page.js

@@ -0,0 +1,94 @@
+// Dependencies
+// ------------
+
+import {extractModuleHint, extractFunctionHint} from './hints-extraction'
+import $ from 'jquery'
+
+// Constants
+// ---------
+
+const contentInner = '.content-inner'
+const projectMetaTag = 'meta[name="project"]'
+const message = {hint: {}, ready: false, requestId: null}
+
+/**
+ *  Will try to extract hint info, and if successful triggers a message to the parent page.
+ */
+function sendHint () {
+  const params = new URLSearchParams(window.location.search)
+  const requestId = params.get('requestId')
+  const hash = window.location.hash
+  const content = $(contentInner)
+  let hint = null
+
+  if (!params.has('hint')) { return }
+
+  if (!requestId) { return }
+
+  const infoElement = descriptionElementFromHash(hash)
+
+  if (infoElement && infoElement.length > 0) {
+    hint = extractFunctionHint(infoElement)
+  } else if (isModulePage()) {
+    hint = extractModuleHint(content)
+  }
+
+  if (!hint) { return }
+
+  hint.version = getProjectVersion()
+
+  postMessage(hint, requestId)
+}
+
+/**
+ * Sends a message (containing everything needed to display a tooltip hint) to the parent page.
+ */
+function postMessage (hint, requestId) {
+  if (window.self !== window.parent) {
+    message.hint = hint
+    message.ready = true
+    message.requestId = requestId
+    window.parent.postMessage(message, '*')
+  }
+}
+
+/**
+ * Checks if the current page is dedicated to a module.
+ *
+ * @returns {boolean} `true` if current page contains module documentation.
+ */
+function isModulePage () {
+  return $(contentInner).find('#moduledoc').length > 0
+}
+
+/**
+ * Constructs a jQuery selector targeting an element
+ *
+ * @param {Object} params URLSearchParams object, parsed parameters from the URL
+ *
+ * @returns {object} jquery selector
+ */
+function descriptionElementFromHash (hash) {
+  if (!hash) { return null }
+  hash = hash.substr(1) // removes the `#` in `#hash`
+
+  if (!hash) { return null }
+  hash = $.escapeSelector(hash)
+
+  if (!hash) { return null }
+
+  return $(`#${hash}.detail`)
+}
+
+function getProjectVersion () {
+  return $(projectMetaTag).attr('content')
+}
+
+// Public Methods
+// --------------
+
+export function initialize () {
+  $(document).ready(function () {
+    sendHint()
+  })
+}