Merge pull request #81 from webdoc-labs/feature/tables+explorer-expand

Feature: Summary tables + Explorer expand & auto-scroll

Author: ShukantPal

packages/webdoc-default-template/helper/renderer-plugins/category-filter.js

@@ -15,6 +15,9 @@ exports.categoryFilterPlugin = (doc /*: Doc */, constraints /*: CategoryConstrai
         return false;
       }
     }
+    if (child.inherited && !child.overrides) {
+      return;
+    }
 
     if (child.type === "MethodDoc" && child.name === "constructor") {
       return false;// Filter constructors always!

packages/webdoc-default-template/helper/renderer-plugins/signature.js

@@ -5,7 +5,7 @@ import type {Doc} from "@webdoc/types";
 const {linker} = require("../linker");
 
 exports.signaturePlugin = {
-  generateSignature(doc /*: Doc */) {
+  generateSignature(doc /*: Doc */, options = {} /*: { noTail: boolean } */) {
     const mapDocTypeToKeyboard = {
       ClassDoc: "class",
       NSDoc: "namespace",
@@ -48,7 +48,7 @@ exports.signaturePlugin = {
             .join(", ")
         })`;
       }
-      if (doc.returns) {
+      if (!options.noTail && doc.returns) {
         signature += ` → {${
           (doc.returns || [])
             .map((returns) => (returns.dataType ?
@@ -59,7 +59,7 @@ exports.signaturePlugin = {
       }
       break;
     case "PropertyDoc":
-      if (doc.dataType) {
+      if (!options.noTail && doc.dataType) {
         signature += ": " + linker.linkTo(doc.dataType, undefined, {htmlSafe: false});
       }
       break;

packages/webdoc-default-template/publish.js

@@ -6,6 +6,7 @@ const path = require("path");
 const {traverse} = require("@webdoc/model");
 const {
   FlushToFile,
+  RelationsPlugin,
   TemplateRenderer,
   TemplatePipeline,
   TemplateTagsResolver,
@@ -62,11 +63,14 @@ exports.publish = (options /*: PublishOptions */) => {
     .installPlugin("linker", linker)
     .installPlugin("generateIndex", indexSorterPlugin)
     .installPlugin("signature", signaturePlugin)
-    .installPlugin("categoryFilter", categoryFilterPlugin);
+    .installPlugin("categoryFilter", categoryFilterPlugin)
+    .installPlugin("relations", RelationsPlugin);
   const pipeline = new TemplatePipeline(renderer)
     .pipe(new TemplateTagsResolver())
     .pipe(new FlushToFile({skipNullFile: false}));
 
+  renderer.getPlugin("relations").buildRelations();
+
   idToDoc = new Map();
 
   traverse(docTree, (doc) => {

packages/webdoc-default-template/src/app/components/Explorer/ExplorerItem.js

@@ -1,8 +1,13 @@
-import {useExplorerCategoryStyles, useExplorerStyles} from "./useExplorerStyles";
+import {
+  useExplorerCategoryStyles,
+  useExplorerPrimaryItemStyles,
+  useExplorerStyles,
+} from "./useExplorerStyles";
 import ExplorerCategoryItem from "./ExplorerCategoryItem";
 import Link from "@material-ui/core/Link";
 import React from "react";
 import TreeItem from "@material-ui/lab/TreeItem";
+import {isSamePage} from "./helpers";
 
 export default function ExplorerItem(props) {
   if (!props.data.$nodeId) {
@@ -11,6 +16,7 @@ export default function ExplorerItem(props) {
 
   const classesItem = useExplorerStyles();
   const classesCategory = useExplorerCategoryStyles();
+  const classesPrimaryItem = useExplorerPrimaryItemStyles();
   const targetChildren = [];
 
   let i = 0;
@@ -24,6 +30,11 @@ export default function ExplorerItem(props) {
 
   const classes = i > 0 ? classesCategory : classesItem;
   const nodeId = props.data.$nodeId;
+  const primary = props.data.page && isSamePage(props.data);
+
+  if (primary) {
+    console.log(props.data);
+  }
 
   const toggle = React.useCallback(
     () => props.toggle(nodeId),
@@ -36,6 +47,7 @@ export default function ExplorerItem(props) {
 
   return (
     <TreeItem
+      id={props.data.$nodeId}
       className="explorer-tree__target"
       classes={{
         label: classes.label,
@@ -47,7 +59,7 @@ export default function ExplorerItem(props) {
       label={
         props.data.page ?
           (
-            <Link classes={{root: classes.labelLinks}}
+            <Link classes={{root: primary ? classesPrimaryItem.labelLinks : classes.labelLinks}}
               href={props.data.page}
               underline="hover"
             >

packages/webdoc-default-template/src/app/components/Explorer/helpers.js

@@ -0,0 +1,13 @@
+export function isSamePage(data) {
+  const path = window.location.pathname.includes(".html") ?
+    window.location.pathname :
+    `${window.location.pathname}.html`;
+
+  if (data.page.startsWith("/") && data.page === path) {
+    return true;
+  } else if (!data.page.startsWith("/") && path.includes(`/${data.page}`)) {
+    return true;
+  }
+
+  return false;
+}

packages/webdoc-default-template/src/app/components/Explorer/index.js

@@ -8,19 +8,36 @@ import React from "react";
 import TreeView from "@material-ui/lab/TreeView";
 import {connect} from "react-redux";
 import cuid from "cuid";
+import {isSamePage} from "./helpers";
 import store from "../../store";
 import {useExplorerStyles} from "./useExplorerStyles";
 
 let fetched = false;
 
-function makeIds(data) {
+function makeIds(data, collector) {
   data.$nodeId = cuid();
 
+  let shouldBeExpanded = false;
+
+  if (data.page) {
+    shouldBeExpanded = isSamePage(data);
+  }
+
   if (data.children) {
     for (const [, value] of Object.entries(data.children)) {
-      makeIds(value);
+      const childExpanded = makeIds(value, collector);
+
+      if (childExpanded) {
+        collector.add(data.$nodeId);
+        shouldBeExpanded = true;
+      }
     }
   }
+  if (shouldBeExpanded) {
+    collector.add(data.$nodeId);
+  }
+
+  return shouldBeExpanded;
 }
 
 export default connect(({
@@ -35,6 +52,14 @@ export default connect(({
     value: isOpen,
   }),
   expandedItems: Array.from(expandedItems),
+  setAutoScrollTo: (value) => store.dispatch({
+    type: "setAutoScrollTo",
+    value,
+  }),
+  setExpandedItems: (value) => store.dispatch({
+    type: "setExpandedItems",
+    value,
+  }),
   toggleItem: (nodeId, optValue) => store.dispatch({
     type: "toggleItem",
     nodeId,
@@ -44,9 +69,12 @@ export default connect(({
   isOpen,
   setOpen,
   expandedItems,
+  setExpandedItems,
   toggleItem,
+  rootRef,
 }) {
   const [data, setData] = React.useState(null);
+  const [autoScrollTo, setAutoScrollTo] = React.useState(null);
   const {root} = useExplorerStyles();
   const toggleOpen = React.useCallback(() => setOpen(!isOpen), [isOpen]);
   const children = [];
@@ -57,8 +85,12 @@ export default connect(({
       .then((response) => {
         if (response.ok) {
           response.json().then((idata) => {
-            makeIds(idata);
+            const defaultExpanded = new Set();
+
+            makeIds(idata, defaultExpanded);
             setData(idata || {});
+            setAutoScrollTo(defaultExpanded.values().next().value);
+            setExpandedItems(defaultExpanded);
           });
         } else {
           throw new Error("Can't fetch reference.json");
@@ -87,6 +119,29 @@ export default connect(({
     children.push(<span key={++i}>Loading...</span>);
   }
 
+  React.useEffect(
+    () => {
+      setTimeout(
+        () => {
+          const scrollEl = rootRef.current.querySelector(".MuiTreeView-root");
+          const toEl = document.getElementById(autoScrollTo);
+
+          if (scrollEl && toEl) {
+            const rect = toEl.getBoundingClientRect();
+
+            scrollEl.scrollTo({
+              left: rect.left,
+              top: rect.top - 124,
+              behavior: "smooth",
+            });
+          }
+        },
+        400,
+      );
+    },
+    [autoScrollTo],
+  );
+
   return (
     <div className="explorer" style={{
       transition: "margin-left 200ms, width 200ms",

packages/webdoc-default-template/src/app/components/Explorer/useExplorerStyles.js

@@ -34,3 +34,10 @@ export const useExplorerCategoryStyles = makeStyles({
     fontWeight: "bold !important",
   },
 });
+
+export const useExplorerPrimaryItemStyles = makeStyles({
+  labelLinks: {
+    ...itemStyle.labelLinks,
+    color: "#0066CD !important",
+  },
+});

packages/webdoc-default-template/src/app/index.js

@@ -6,6 +6,8 @@ import ReactDOM from "react-dom";
 import store from "./store";
 
 window.onload = function() {
+  wakeAccordions();
+
   const appBarRoot = document.getElementById("header-mount-point");
   const explorerRoot = document.getElementById("explorer-mount-point");
   const footerRoot = document.getElementById("footer-mount-point");
@@ -22,7 +24,7 @@ window.onload = function() {
   ReactDOM.render(
     (
       <Provider store={store}>
-        <Explorer />
+        <Explorer rootRef={{current: explorerRoot}} />
       </Provider>
     ),
     explorerRoot,
@@ -35,3 +37,15 @@ window.onload = function() {
     footerRoot,
   );
 };
+
+function wakeAccordions() {
+  document.querySelectorAll(".accordion").forEach(
+    (accordion) => {
+      const btn = accordion.querySelector(".accordion__toggle");
+
+      btn.onclick = () => {
+        accordion.classList.toggle("accordion-active");
+      };
+    },
+  );
+}

packages/webdoc-default-template/src/app/store.js

@@ -26,6 +26,11 @@ function globalReducer(state = {}, action) {
         query: action.value,
       };
     }
+  case "setExpandedItems":
+    return {
+      ...state,
+      expandedItems: new Set(action.value),
+    };
   case "toggleItem": {
     const expandedItems = new Set(state.expandedItems);
 

packages/webdoc-default-template/src/styles/members.scss

@@ -10,8 +10,17 @@
     padding: 8px;
   }
 
+  &__subcategory {
+    color: #333;
+    font-size: 1.125em;
+    font-weight: normal;
+    line-height: 1.4em;
+    margin: 14px 8px 14px 0;
+  }
+
   > hr {
-    border: 2px solid $colorSheetSecondary
+    border: 1px solid $colorSheetSecondary;
+    margin-bottom: 10px;
   }
 
   > * {
@@ -50,3 +59,57 @@
     margin-bottom: 8px;
   }
 }
+
+.accordion {
+  &__toggle {
+    align-items: center;
+    border-radius: 8px;
+    display: flex;
+    transition-duration: 200ms;
+
+    button {
+      background: transparent;
+      border: none;
+      height: 40px;
+      padding: 0;
+      width: 40px;
+
+      .accordion__bg-active {
+        display: none;
+      }
+
+      &:focus {
+        outline: none;
+      }
+    }
+
+    &:hover {
+      background-color: rgba(0, 0, 0, 0.04);
+    }
+  }
+
+  &__content {
+    max-height: 0;
+    overflow: hidden;
+    visibility: hidden;
+  }
+}
+
+.accordion-active {
+  > .accordion__content {
+    max-height: max-content;
+    visibility: visible;
+  }
+
+  .accordion__toggle {
+    button {
+      .accordion__bg-inactive {
+        display: none;
+      }
+
+      .accordion__bg-active {
+        display: inline;
+      }
+    }
+  }
+}