Use <details> element for collapsibles (#690)

* Remove unnecessary call to 'collapseSection'

The call is unnecessary since there is no corresponding toggle for hiding the
section of orphan instances.

* Use <details> for collapsibles

This makes them work even when JS is disabled. Closes #560.

Author: timjb

haddock-api/resources/html/Ocean.std-theme/ocean.css

@@ -46,6 +46,14 @@ a[href].def:hover { color: rgb(78, 98, 114); }
 
 /* @end */
 
+/* @group Show and hide with JS */
+
+body.js-enabled .hide-when-js-enabled {
+  display: none;
+}
+
+/* @end */
+
 /* @group Fonts & Sizes */
 
 /* Basic technique & IE workarounds from YUI 3
@@ -106,7 +114,7 @@ pre, code, kbd, samp, tt, .src {
 
 /* @group Common */
 
-.caption, h1, h2, h3, h4, h5, h6 {
+.caption, h1, h2, h3, h4, h5, h6, summary {
   font-weight: bold;
   color: rgb(78,98,114);
   margin: 0.8em 0 0.4em;
@@ -168,6 +176,16 @@ p.caption.expander {
   min-height: 9px;
 }
 
+summary {
+  cursor: pointer;
+  outline: none;
+  list-style-image: url(plus.gif);
+  list-style-position: outside;
+}
+
+details[open] > summary {
+  list-style-image: url(minus.gif);
+}
 
 pre {
   padding: 0.25em;
@@ -338,24 +356,22 @@ div#style-menu-holder {
   z-index: 1;
 }
 
-#synopsis .caption {
+#synopsis summary {
+  display: block;
   float: left;
   width: 29px;
   color: rgba(255,255,255,0);
   height: 110px;
   margin: 0;
   font-size: 1px;
   padding: 0;
+  background: url(synopsis.png) no-repeat 0px -8px;
 }
 
-#synopsis p.caption.collapser {
+#synopsis details[open] > summary {
   background: url(synopsis.png) no-repeat -64px -8px;
 }
 
-#synopsis p.caption.expander {
-  background: url(synopsis.png) no-repeat 0px -8px;
-}
-
 #synopsis ul {
   height: 100%;
   overflow: auto;

haddock-api/resources/html/haddock-bundle.min.js

@@ -0,0 +1,20 @@
+export function setCookie(name: string, value: string) {
+  document.cookie = name + "=" + encodeURIComponent(value) + ";path=/;";
+}
+
+export function clearCookie(name: string) {
+  document.cookie = name + "=;path=/;expires=Thu, 01-Jan-1970 00:00:01 GMT;";
+}
+
+export function getCookie(name: string) {
+  const nameEQ = name + "=";
+  const ca = document.cookie.split(';');
+  for (let i = 0; i < ca.length; i++) {
+    let c = ca[i];
+    while (c.charAt(0)==' ') c = c.substring(1,c.length);
+    if (c.indexOf(nameEQ) == 0) {
+      return decodeURIComponent(c.substring(nameEQ.length,c.length));
+    }
+  }
+  return null;
+}

haddock-api/resources/html/js-src/cookies.ts

@@ -0,0 +1,106 @@
+import {getCookie} from "./cookies";
+
+interface HTMLDetailsElement extends HTMLElement {
+  open: boolean
+}
+
+interface DetailsInfo {
+  element: HTMLDetailsElement
+  openByDefault: boolean
+  toggles: HTMLElement[]
+}
+
+// Global state
+const detailsRegistry: { [id: string]: DetailsInfo } = {};
+const toggled: { [id: string]: true } = {}; /* stores which <details> are not in their default state */
+
+function lookupDetailsRegistry(id: string): DetailsInfo {
+  const info = detailsRegistry[id];
+  if (info == undefined) { throw new Error(`could not find <details> element with id '${id}'`); }
+  return info;
+}
+
+function onDetailsToggle(ev: Event) {
+  const element = ev.target as HTMLDetailsElement;
+  const id = element.id;
+  const info = lookupDetailsRegistry(id);
+  const isOpen = info.element.open;
+  for (const toggle of info.toggles) {
+    if (toggle.classList.contains('details-toggle-control')) {
+      toggle.classList.add(isOpen ? 'collapser' : 'expander');
+      toggle.classList.remove(isOpen ? 'expander' : 'collapser');
+    }
+  }
+  if (element.open == info.openByDefault) {
+    delete toggled[id];
+  } else {
+    toggled[id] = true;
+  }
+  rememberToggled();
+}
+
+function gatherDetailsElements() {
+  const els: HTMLDetailsElement[] = Array.prototype.slice.call(document.getElementsByTagName('details'));
+  for (const el of els) {
+    if (typeof el.id == "string" && el.id.length > 0) {
+      detailsRegistry[el.id] = {
+        element: el,
+        openByDefault: !!el.open,
+        toggles: [] // added later
+      };
+      el.addEventListener('toggle', onDetailsToggle);
+    }
+  }
+}
+
+function toggleDetails(id: string) {
+  const {element} = lookupDetailsRegistry(id);
+  element.open = !element.open;
+}
+
+function rememberToggled() {
+  const sections: string[] = Object.keys(toggled);
+  // cookie specific to this page; don't use setCookie which sets path=/
+  document.cookie = "toggled=" + encodeURIComponent(sections.join('+'));
+}
+
+function restoreToggled() {
+  const cookie = getCookie("toggled");
+  if (!cookie) { return; }
+  const ids = cookie.split('+');
+  for (const id of ids) {
+    const info = detailsRegistry[id];
+    toggled[id] = true;
+    if (info) {
+      info.element.open = !info.element.open;
+    }
+  }
+}
+
+function onToggleClick(ev: MouseEvent) {
+  ev.preventDefault();
+  const toggle = ev.currentTarget as HTMLElement;
+  const id = toggle.getAttribute('data-details-id');
+  if (!id) { throw new Error("element with class 'details-toggle' has no 'data-details-id' attribute!"); }
+  toggleDetails(id);
+}
+
+function initCollapseToggles() {
+  const toggles: HTMLElement[] = Array.prototype.slice.call(document.getElementsByClassName('details-toggle'));
+  toggles.forEach(toggle => {
+    const id = toggle.getAttribute('data-details-id');
+    if (!id) { throw new Error("element with class 'details-toggle' has no 'data-details-id' attribute!"); }
+    const info = lookupDetailsRegistry(id);
+    info.toggles.push(toggle);
+    toggle.addEventListener('click', onToggleClick);
+    if (toggle.classList.contains('details-toggle-control')) {
+      toggle.classList.add(info.element.open ? 'collapser' : 'expander');
+    }
+  });
+}
+
+export function init() {
+  gatherDetailsElements();
+  restoreToggled();
+  initCollapseToggles();
+}

haddock-api/resources/html/js-src/details-helper.ts

@@ -1,4 +1,5 @@
-import * as util from "./haddock-util";
+import * as styleMenu from "./style-menu";
+import * as detailsHelper from "./details-helper";
 import * as quickJump from "./quick-jump";
 
 function onDomReady(callback: () => void) {
@@ -14,8 +15,8 @@ function onDomReady(callback: () => void) {
 }
 
 onDomReady(() => {
-  util.addStyleMenu();
-  util.resetStyle();
-  util.restoreCollapsed();
+  document.body.classList.add('js-enabled');
+  styleMenu.init();
+  detailsHelper.init();
   quickJump.init();
 });

haddock-api/resources/html/js-src/init.ts

@@ -1,5 +1,7 @@
 // Haddock JavaScript utilities
 
+import {getCookie, setCookie, clearCookie} from "./cookies";
+
 const rspace = /\s\s+/g,
     rtrim = /^\s+|\s+$/g;
 
@@ -37,77 +39,13 @@ function toggleClass(elem: Element, valueOn: string, valueOff: string, bool?: bo
   return bool;
 }
 
-
 function makeClassToggle(valueOn: string, valueOff: string): (elem: Element, bool?: boolean) => boolean {
   return function(elem, bool) {
     return toggleClass(elem, valueOn, valueOff, bool);
   }
 }
 
 const toggleShow = makeClassToggle("show", "hide");
-const toggleCollapser = makeClassToggle("collapser", "expander");
-
-function toggleSection(id: string): boolean {
-  const b = toggleShow(document.getElementById("section." + id) as Element);
-  toggleCollapser(document.getElementById("control." + id) as Element, b);
-  rememberCollapsed(id);
-  return b;
-}
-
-// TODO: get rid of global variables
-if (typeof window !== 'undefined') {
-  (window as any).toggleSection = toggleSection;
-}
-
-const collapsed: { [id: string]: boolean } = {};
-function rememberCollapsed(id: string) {
-  if(collapsed[id])
-    delete collapsed[id]
-  else
-    collapsed[id] = true;
-
-  const sections: string[] = [];
-  for(let i in collapsed) {
-    if(collapsed.hasOwnProperty(i))
-      sections.push(i);
-  }
-  // cookie specific to this page; don't use setCookie which sets path=/
-  document.cookie = "collapsed=" + encodeURIComponent(sections.join('+'));
-}
-
-export function restoreCollapsed() {
-  const cookie = getCookie("collapsed");
-  if(!cookie)
-    return;
-
-  const ids = cookie.split('+');
-  for(const i in ids)
-  {
-    if(document.getElementById("section." + ids[i]))
-      toggleSection(ids[i]);
-  }
-}
-
-function setCookie(name: string, value: string) {
-  document.cookie = name + "=" + encodeURIComponent(value) + ";path=/;";
-}
-
-function clearCookie(name: string) {
-  document.cookie = name + "=;path=/;expires=Thu, 01-Jan-1970 00:00:01 GMT;";
-}
-
-function getCookie(name: string) {
-  const nameEQ = name + "=";
-  const ca = document.cookie.split(';');
-  for (let i = 0; i < ca.length; i++) {
-    let c = ca[i];
-    while (c.charAt(0)==' ') c = c.substring(1,c.length);
-    if (c.indexOf(nameEQ) == 0) {
-      return decodeURIComponent(c.substring(nameEQ.length,c.length));
-    }
-  }
-  return null;
-}
 
 function addMenuItem(html: string) {
   const menu = document.getElementById("page-menu");
@@ -123,7 +61,7 @@ function styles(): HTMLLinkElement[] {
   return es.filter((a: HTMLLinkElement) => a.rel.indexOf("style") != -1 && a.title);
 }
 
-export function addStyleMenu() {
+function addStyleMenu() {
   const as = styles();
   let btns = "";
   as.forEach((a) => {
@@ -162,12 +100,17 @@ function setActiveStyleSheet(title: string) {
   styleMenu(false);
 }
 
-export function resetStyle() {
+function resetStyle() {
   const s = getCookie("haddock-style");
   if (s) setActiveStyleSheet(s);
 }
 
 function styleMenu(show?: boolean) {
   const m = document.getElementById('style-menu');
   if (m) toggleShow(m, show);
+}
+
+export function init() {
+  addStyleMenu();
+  resetStyle();
 }

haddock-api/resources/html/js-src/haddock-util.ts renamed to haddock-api/resources/html/js-src/style-menu.ts

@@ -310,11 +310,11 @@ mkNode qual ss p (Node s leaf pkg srcPkg short ts) =
   htmlModule <+> shortDescr +++ htmlPkg +++ subtree
   where
     modAttrs = case (ts, leaf) of
-      (_:_, False) -> collapseControl p True "module"
+      (_:_, False) -> collapseControl p "module"
       (_,   _    ) -> [theclass "module"]
 
     cBtn = case (ts, leaf) of
-      (_:_, True) -> thespan ! collapseControl p True "" << spaceHtml
+      (_:_, True) -> thespan ! collapseControl p "" << spaceHtml
       (_,   _   ) -> noHtml
       -- We only need an explicit collapser button when the module name
       -- is also a leaf, and so is a link to a module page. Indeed, the
@@ -332,7 +332,12 @@ mkNode qual ss p (Node s leaf pkg srcPkg short ts) =
     shortDescr = maybe noHtml (origDocToHtml qual) short
     htmlPkg = maybe noHtml (thespan ! [theclass "package"] <<) srcPkg
 
-    subtree = mkNodeList qual (s:ss) p ts ! collapseSection p True ""
+    subtree =
+      if null ts then noHtml else
+      collapseDetails p DetailsOpen (
+        thesummary ! [ theclass "hide-when-js-enabled" ] << "Submodules" +++
+        mkNodeList qual (s:ss) p ts
+      )
 
 
 
@@ -586,10 +591,12 @@ ifaceToHtml maybe_source_url maybe_wiki_url iface unicode qual
       | no_doc_at_all = noHtml
       | otherwise
       = divSynopsis $
-            paragraph ! collapseControl "syn" False "caption" << "Synopsis" +++
-            shortDeclList (
-                mapMaybe (processExport True linksInfo unicode qual) exports
-            ) ! (collapseSection "syn" False "" ++ collapseToggle "syn")
+            collapseDetails "syn" DetailsClosed (
+              thesummary << "Synopsis" +++
+              shortDeclList (
+                  mapMaybe (processExport True linksInfo unicode qual) exports
+              ) ! collapseToggle "syn" ""
+            )
 
         -- if the documentation doesn't begin with a section header, then
         -- add one ("Documentation").

haddock-api/src/Haddock/Backends/Xhtml.hs

@@ -165,9 +165,9 @@ hackMarkup fmt' h' =
       UntouchedDoc d -> (markup fmt $ _doc d, [_meta d])
       CollapsingHeader (Header lvl titl) par n nm ->
         let id_ = makeAnchorId $ "ch:" ++ fromMaybe "noid:" nm ++ show n
-            expanded = False
-            col' = collapseControl id_ expanded "caption"
-            instTable = (thediv ! collapseSection id_ expanded [] <<)
+            col' = collapseControl id_ "caption"
+            summary = thesummary ! [ theclass "hide-when-js-enabled" ] << "Expand"
+            instTable contents = collapseDetails id_ DetailsClosed (summary +++ contents)
             lvs = zip [1 .. ] [h1, h2, h3, h4, h5, h6]
             getHeader = fromMaybe caption (lookup lvl lvs)
             subCaption = getHeader ! col' << markup fmt titl