Add Reference Popovers

assets/js/app.js

@@ -31,6 +31,8 @@ import {initialize as initNightMode} from './night'
 import {initialize as initMakeup} from './makeup'
 import {initialize as initKeyboardShortcuts} from './keyboard-shortcuts'
 import {initialize as initQuickSwitch} from './quick-switch'
+import {initialize as initTooltips} from './tooltips/tooltips'
+import {initialize as initHintsPage} from './tooltips/hints-page'
 
 window.$ = $
 
@@ -67,5 +69,8 @@ $(() => {
   initMakeup()
   initKeyboardShortcuts()
   initQuickSwitch()
+  initTooltips()
+  initHintsPage()
+
   hljs.initHighlighting()
 })

assets/js/keyboard-shortcuts.js

@@ -61,7 +61,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,20 @@
+{{#if isType}}
+  <section class="docstring docstring-type">
+    {{this.hint.description}}
+  </section>
+{{else}}
+  <div class="detail-header">
+    <h1 class="signature">
+      {{this.hint.title}}
+      <div class="version-info">{{this.hint.version}}</div>
+    </h1>
+    {{#unless this.isModule}}
+      <div class="specs">{{this.hint.signatureSpecs}}</div>
+    {{/unless}}
+  </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,107 @@
+// 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 = decodeURI(hash)
+  hash = $.escapeSelector(hash)
+
+  if (!hash) { return null }
+
+  const mainSelector = $(`#${hash}.detail`)
+
+  if (mainSelector.length > 0) {
+    return mainSelector
+  } else {
+    return $(`.detail > span#${hash}`).parent()
+  }
+}
+
+/**
+ * Grabs project version name from the meta tag.
+ *
+ * @returns {string} Project version name (ie. "Elixir v1.2.3")
+ */
+function getProjectVersion () {
+  return $(projectMetaTag).attr('content')
+}
+
+// Public Methods
+// --------------
+
+export function initialize () {
+  $(document).ready(function () {
+    sendHint()
+  })
+}