mobility-toolbox-js 2.0.0-beta.3 → 2.0.0-beta.6

package/src/doc/components/Esdoc/DocLinkHTML.js

@@ -0,0 +1,62 @@
+/* eslint-disable no-param-reassign */
+/* eslint-disable react/prop-types */
+/* eslint-disable react/no-danger */
+import React from 'react';
+import Anchor from './Anchor';
+import { _findByName, _getURL } from './DocBuilderUtils';
+
+/**
+ * build html link to file page.
+ * https://github.com/esdoc/esdoc-plugins/blob/2de5022baa569785a189056a99acd1d7ca8284b7/esdoc-publish-html-plugin/src/Builder/DocBuilder.js#L592
+ * @param {DocObject} doc - target doc object.
+ * @param {string} text - link text.
+ * @returns {string} html of link.
+ * @private
+ */
+function DocLinkHTML({ longname, text = null, inner = false, kind = null }) {
+  if (!longname) return '';
+
+  if (typeof longname !== 'string') throw new Error(JSON.stringify(longname));
+
+  const doc = _findByName(longname, kind)[0];
+
+  if (!doc) {
+    // Special links to typedefs main page
+    if (longname === 'typedefs') {
+      return (
+        <span>
+          <a href="/api/typedef/index%20html">{text || longname}</a>
+        </span>
+      );
+    }
+    // if longname is HTML tag, not escape.
+    if (longname.indexOf('<') === 0) {
+      return <span dangerouslySetInnerHTML={{ __html: longname }} />;
+    }
+    return <span>{text || longname}</span>;
+  }
+
+  if (doc.kind === 'external') {
+    text = doc.name;
+    return (
+      <span>
+        <a target="_blank" rel="noreferrer" href={doc.externalLink}>
+          {text}
+        </a>
+      </span>
+    );
+  }
+  text = text || doc.name;
+  const url = _getURL(doc, inner);
+  if (url) {
+    return (
+      <span>
+        <Anchor path={`/api/${url.replace(/\./g, '%20')}-offset-anchor`}>
+          {text}
+        </Anchor>
+      </span>
+    );
+  }
+  return <span>{text}</span>;
+}
+export default React.memo(DocLinkHTML);

package/src/doc/components/Esdoc/DocsLinkHTML.js

@@ -0,0 +1,38 @@
+/* eslint-disable react/prop-types */
+import React from 'react';
+import DocLinkHTML from './DocLinkHTML';
+
+/**
+ * build html links to identifiers
+ * https://github.com/esdoc/esdoc-plugins/blob/2de5022baa569785a189056a99acd1d7ca8284b7/esdoc-publish-html-plugin/src/Builder/DocBuilder.js#L788
+ * @param {string[]} longnames - link to these.
+ * @param {string} [text] - link text. default is name property of doc object.
+ * @param {boolean} [inner=false] - if true, use inner link.
+ * @param {string} [separator='\n'] - used link separator.
+ * @returns {string} html links.
+ * @private
+ */
+function DocsLinkHTML({
+  longnames,
+  text = null,
+  inner = false,
+  separator = '\n',
+}) {
+  if (!longnames) return '';
+  if (!longnames.length) return '';
+
+  const nonNullLongNames = longnames.filter((longname) => !!longname);
+  if (!nonNullLongNames.length) return '';
+
+  return (
+    <ul>
+      {nonNullLongNames.map((longname, idx) => (
+        <li key={longname}>
+          <DocLinkHTML longname={longname} text={text} inner={inner} />
+          {idx !== longnames.length - 1 ? `${separator}` : ''}
+        </li>
+      ))}
+    </ul>
+  );
+}
+export default React.memo(DocsLinkHTML);

package/src/doc/components/Esdoc/Esdoc.js

@@ -0,0 +1,63 @@
+/* eslint-disable react/prop-types */
+import React from 'react';
+import { makeStyles } from '@material-ui/core/styles';
+import Grid from '@material-ui/core/Grid';
+import Hidden from '@material-ui/core/Hidden';
+import EsdocContent from './EsdocContent';
+import EsdocNavigation from './EsdocNavigation';
+import EsdocSearch from './EsdocSearch';
+import { version } from '../../../../package.json';
+import './css/style.css';
+
+const useStyles = makeStyles((theme) => ({
+  root: {
+    width: '100%',
+  },
+  content: {
+    padding: theme.spacing(1),
+    paddingBottom: 115,
+    margin: '0 auto',
+    maxWidth: '740px',
+  },
+  navWrapper: {
+    height: 'calc(100% - 32px)',
+    padding: theme.spacing(2),
+    backgroundColor: 'rgb(239, 239, 239)',
+  },
+}));
+
+function Esdoc({ path }) {
+  const classes = useStyles();
+
+  if (!path) {
+    return null;
+  }
+
+  return (
+    <div className={`esdoc ${classes.root}`}>
+      <Hidden smUp>
+        <Grid container>
+          <Grid item xs={12} className={classes.content}>
+            <EsdocContent path={path} />
+          </Grid>
+        </Grid>
+      </Hidden>
+      <Hidden only="xs">
+        <Grid container wrap="nowrap">
+          <Grid item style={{ minWidth: 260, maxWidth: 300 }}>
+            <div className={classes.navWrapper}>
+              {version}
+              <EsdocSearch />
+              <EsdocNavigation />
+            </div>
+          </Grid>
+          <Grid item xs={9} className={classes.content}>
+            <EsdocContent path={path} />
+          </Grid>
+        </Grid>
+      </Hidden>
+    </div>
+  );
+}
+
+export default React.memo(Esdoc);

package/src/doc/components/Esdoc/EsdocContent.js

@@ -0,0 +1,51 @@
+/* eslint-disable react/prop-types */
+import React from 'react';
+import docss from './index.json';
+import ClassDoc from './ClassDoc';
+import IdentifiersDoc from './IdentifiersDoc';
+import SingleDoc from './SingleDoc';
+import {
+  _resolveExtendsChain,
+  _resolveNecessary,
+  _resolveIgnore,
+  _resolveLink,
+} from './DocBuilderUtils';
+
+// Preprocess the index.json content.
+// https://github.com/esdoc/esdoc-plugins/blob/2de5022baa569785a189056a99acd1d7ca8284b7/esdoc-publish-html-plugin/src/Builder/DocResolver.js
+let docs = _resolveExtendsChain(docss);
+docs = _resolveNecessary(docs);
+docs = _resolveIgnore(docs);
+docs = _resolveLink(docs);
+
+function EsdocContent({ path }) {
+  let doc;
+
+  if (!path) {
+    return null;
+  }
+
+  const [firstPath] = path.split('#')[0].split('/');
+  if (path) {
+    doc = docs.find((item) => {
+      const [docLongName] = item.longname.split('#');
+      const reg = new RegExp(docLongName);
+      if (reg.test(path) && item.kind === 'class') {
+        return item;
+      }
+      return null;
+    });
+  }
+
+  return (
+    <div className="content">
+      {/^identifiers/.test(path) && <IdentifiersDoc docs={docs} />}
+      {firstPath === 'class' && doc && <ClassDoc doc={doc} />}
+      {firstPath === 'variable' && <SingleDoc kind={firstPath} />}
+      {firstPath === 'typedef' && <SingleDoc kind={firstPath} />}
+      {firstPath === 'function' && <SingleDoc kind={firstPath} />}
+    </div>
+  );
+}
+
+export default React.memo(EsdocContent);

package/src/doc/components/Esdoc/EsdocNavigation.js

@@ -0,0 +1,13 @@
+/* eslint-disable react/prop-types */
+import React from 'react';
+import NavDoc from './NavDoc';
+
+function EsdocNavigation() {
+  return (
+    <div className="navigation">
+      <NavDoc />
+    </div>
+  );
+}
+
+export default React.memo(EsdocNavigation);

package/src/doc/components/Esdoc/EsdocSearch.js

@@ -0,0 +1,81 @@
+import React, { useState, useMemo } from 'react';
+import { makeStyles } from '@material-ui/core/styles';
+import { TextField } from '@material-ui/core';
+import { _getSearchIndex } from './DocBuilderUtils';
+
+const useStyles = makeStyles(() => ({
+  filterField: {
+    width: '100%',
+  },
+  searchWrapper: {
+    backgroundColor: 'white',
+  },
+}));
+
+function EsdocSearch() {
+  const searchIndex = _getSearchIndex();
+  const classes = useStyles();
+  const [filter, setFilter] = useState('');
+
+  const resultsByKind = useMemo(() => {
+    const tmp = {
+      class: [],
+      method: [],
+      member: [],
+      function: [],
+      variable: [],
+      typedef: [],
+      external: [],
+      file: [],
+      test: [],
+      testFile: [],
+    };
+    for (let i = 0; i < searchIndex.length; i += 1) {
+      const pair = searchIndex[i];
+      if (filter && pair[0].indexOf(filter.toLowerCase()) > -1) {
+        const kind = pair[3];
+        tmp[kind].push(pair);
+      }
+    }
+    return tmp;
+  }, [filter, searchIndex]);
+
+  return (
+    <div className={`search-box active ${classes.searchWrapper}`}>
+      <TextField
+        inputProps={{
+          style: {
+            padding: 8,
+            fontSize: 16,
+          },
+        }}
+        variant="outlined"
+        className={classes.filterField}
+        placeholder="Search..."
+        value={filter}
+        onChange={(e) => setFilter(e.target.value)}
+      />
+      <ul className="search-result">
+        {Object.entries(resultsByKind).map(([kind, result]) => {
+          return (
+            !!result.length && (
+              <React.Fragment key={kind}>
+                <li className="search-separator">{kind}</li>
+                {result.map((pair) => {
+                  return (
+                    <li>
+                      <a href={`/api/${pair[1]}`.replace(/\./g, '%20')}>
+                        {pair[2]}
+                      </a>
+                    </li>
+                  );
+                })}
+              </React.Fragment>
+            )
+          );
+        })}
+      </ul>
+    </div>
+  );
+}
+export default EsdocSearch;

package/src/doc/components/Esdoc/ExperimentalHTML.js

@@ -0,0 +1,17 @@
+/**
+ * build experimental html.
+ * https://github.com/esdoc/esdoc-plugins/blob/2de5022baa569785a189056a99acd1d7ca8284b7/esdoc-publish-html-plugin/src/Builder/DocBuilder.js#L936
+ * @param {DocObject} doc - target doc object.
+ * @returns {string} if doc is not experimental, returns empty.
+ * @private
+ */
+const ExperimentalHTML = (doc) => {
+  if (doc.experimental) {
+    const experimental = [`this ${doc.kind} is experimental.`];
+    if (typeof doc.experimental === 'string')
+      experimental.push(doc.experimental);
+    return experimental.join(' ');
+  }
+  return '';
+};
+export default ExperimentalHTML;

package/src/doc/components/Esdoc/ExtendsChainHTML.js

@@ -0,0 +1,32 @@
+/* eslint-disable react/prop-types */
+/* eslint-disable no-underscore-dangle */
+import React from 'react';
+import DocLinkHTML from './DocLinkHTML';
+
+/**
+ * build class ancestor extends chain.
+ * https://github.com/esdoc/esdoc-plugins/blob/2de5022baa569785a189056a99acd1d7ca8284b7/esdoc-publish-html-plugin/src/Builder/ClassDocBuilder.js#L172
+ * @param {DocObject} doc - target class doc.
+ * @returns {string} extends chain links html.
+ * @private
+ */
+function ExtendsChainHTML({ doc }) {
+  if (!doc._custom_extends_chains) return '';
+  if (doc.extends.length > 1) return '';
+
+  return (
+    <div className="flat-list" data-ice="extendsChain">
+      <h4>Extends:</h4>
+      <div>
+        {doc._custom_extends_chains.map((extend) => (
+          <React.Fragment key={extend}>
+            <DocLinkHTML longname={extend} />
+            {' → '}
+          </React.Fragment>
+        ))}
+        {doc.name}
+      </div>
+    </div>
+  );
+}
+export default React.memo(ExtendsChainHTML);

package/src/doc/components/Esdoc/FileDocLinkHTML.js

@@ -0,0 +1,60 @@
+/* eslint-disable no-param-reassign */
+/* eslint-disable prefer-destructuring */
+/* eslint-disable react/prop-types */
+import React from 'react';
+
+import { _find, _getURL } from './DocBuilderUtils';
+
+/**
+ * build html link to file page.
+ * https://github.com/esdoc/esdoc-plugins/blob/2de5022baa569785a189056a99acd1d7ca8284b7/esdoc-publish-html-plugin/src/Builder/DocBuilder.js#L592
+ * @param {DocObject} doc - target doc object.
+ * @param {string} text - link text.
+ * @returns {string} html of link.
+ * @private
+ */
+function FileDocLinkHTML({ doc, text }) {
+  if (!doc) return null;
+
+  if (text === 'source' && doc.memberof) {
+    return (
+      <span>
+        <a
+          target="_blank"
+          rel="noreferrer"
+          href={`https://github.com/geops/mobility-toolbox-js/blob/master/${
+            doc.memberof.split('~')[0]
+          }#L${doc.lineNumber}`}
+        >
+          {text}
+        </a>
+      </span>
+    );
+  }
+
+  let fileDoc;
+  if (doc.kind === 'file' || doc.kind === 'testFile') {
+    fileDoc = doc;
+  } else {
+    const filePath = doc.longname.split('~')[0];
+    fileDoc = _find({ kind: ['file', 'testFile'], name: filePath })[0];
+  }
+
+  if (!fileDoc) return '';
+
+  if (!text) text = fileDoc.name;
+
+  if (doc.kind === 'file' || doc.kind === 'testFile') {
+    return (
+      <span>
+        <a href={`${_getURL(fileDoc)}`}>{text}</a>
+      </span>
+    );
+  }
+  return (
+    <span>
+      <a href={`${_getURL(fileDoc)}#lineNumber${doc.lineNumber}`}>{text}</a>
+    </span>
+  );
+}
+export default React.memo(FileDocLinkHTML);

package/src/doc/components/Esdoc/IdentifiersDoc.js

@@ -0,0 +1,113 @@
+/* eslint-disable no-continue */
+/* eslint-disable no-restricted-syntax */
+/* eslint-disable no-underscore-dangle */
+/* eslint-disable react/prop-types */
+import React from 'react';
+import path from 'path';
+import SummaryDoc from './SummaryDoc';
+import { escapeURLHash } from './DocBuilderUtils';
+
+/**
+ * build identifier output.
+ * https://github.com/esdoc/esdoc-plugins/blob/2de5022baa569785a189056a99acd1d7ca8284b7/esdoc-publish-html-plugin/src/Builder/IdentifiersDocBuilder.js#L18
+ * @return {IceCap} built output.
+ * @private
+ */
+function IdentifiersDoc({ docs }) {
+  // traverse docs and create Map<dirPath, doc[]>
+  const dirDocs = new Map();
+  const kinds = ['class', 'interface', 'function', 'variable'];
+  //   'typedef',
+  //   'external',
+  // ];
+  const filteredDocs = docs.filter((doc) => {
+    return kinds.includes(doc.kind) && !doc.ignore && doc.access === 'public';
+  });
+
+  // Add a typedef doc to have a link to main type def page
+  filteredDocs.push({
+    access: 'public',
+    description: null,
+    export: false,
+    importPath: 'mobility-toolbox-js/src/index.js',
+    importStyle: 'typedef',
+    kind: 'typedef',
+    lineNumber: 1,
+    longname: 'typedefs',
+    memberof: 'src/index.js',
+    name: 'typedefs',
+    static: true,
+    undocument: true,
+  });
+
+  for (const doc of filteredDocs) {
+    const filePath = doc.memberof.replace(/^.*?[/]/, '');
+    const dirPath = path.dirname(filePath);
+    if (!dirDocs.has(dirPath)) dirDocs.set(dirPath, []);
+    dirDocs.get(dirPath).push(doc);
+  }
+
+  // create a summary of dir
+  const dirPaths = Array.from(dirDocs.keys()).sort((a, b) => (a > b ? 1 : -1));
+  const kindOrder = {
+    class: 0,
+    interface: 1,
+    function: 2,
+    variable: 3,
+    typedef: 4,
+    external: 5,
+  };
+
+  return (
+    <>
+      <h1>References</h1>
+
+      <div className="identifiers-wrap">
+        {dirPaths.map((dirPath) => {
+          const newDirDocs = dirDocs.get(dirPath);
+
+          // see: DocBuilder#_buildNavDoc
+          newDirDocs.sort((a, b) => {
+            const filePathA = a.longname.split('~')[0];
+            const filePathB = b.longname.split('~')[0];
+            const dirPathA = path.dirname(filePathA);
+            const dirPathB = path.dirname(filePathB);
+            const kindA = a.interface ? 'interface' : a.kind;
+            const kindB = b.interface ? 'interface' : b.kind;
+            if (dirPathA === dirPathB) {
+              if (kindA === kindB) {
+                return a.longname > b.longname ? 1 : -1;
+              }
+              return kindOrder[kindA] > kindOrder[kindB] ? 1 : -1;
+            }
+            return dirPathA > dirPathB ? 1 : -1;
+          });
+
+          const dirPathLabel = dirPath === '.' ? '' : dirPath;
+          return (
+            <div key={dirPathLabel} data-ice="dirSummaryWrap">
+              <h2 data-ice="dirPath" id={escapeURLHash(dirPath)}>
+                {dirPathLabel || '/'}
+              </h2>
+              <div data-ice="dirSummary">
+                <SummaryDoc
+                  docs={newDirDocs}
+                  title="summary"
+                  innerLink={false}
+                  kindIcon
+                />
+              </div>
+            </div>
+          );
+        })}
+        {/* TODO
+        <div className="identifier-dir-tree" data-ice="dirTreeWrap">
+          <div className="identifier-dir-tree-header">Directories</div>
+          <div className="identifier-dir-tree-content" data-ice="dirTree" />
+        </div> */}
+      </div>
+    </>
+  );
+}
+
+export default React.memo(IdentifiersDoc);

package/src/doc/components/Esdoc/IndirectSubclassHTML.js

@@ -0,0 +1,30 @@
+/* eslint-disable react/prop-types */
+/* eslint-disable no-underscore-dangle */
+import React from 'react';
+import DocLinkHTML from './DocLinkHTML';
+
+/**
+ * build in-direct subclass list.
+ * https://github.com/esdoc/esdoc-plugins/blob/2de5022baa569785a189056a99acd1d7ca8284b7/esdoc-publish-html-plugin/src/Builder/ClassDocBuilder.js#L186
+ * @param {DocObject} doc - target class doc.
+ * @returns {string} html of in-direct subclass links.
+ * @private
+ */
+function IndirectSubclassHTML({ doc }) {
+  if (!doc._custom_indirect_subclasses) return '';
+
+  return (
+    <div className="flat-list" data-ice="directSubclass">
+      <h4>Direct Subclass:</h4>
+      <div>
+        {doc._custom_indirect_subclasses.map((extend, idx) => (
+          <React.Fragment key={extend}>
+            <DocLinkHTML longname={extend} />
+            {idx !== doc._custom_indirect_subclasses.length - 1 ? ', ' : ''}
+          </React.Fragment>
+        ))}
+      </div>
+    </div>
+  );
+}
+export default React.memo(IndirectSubclassHTML);

package/src/doc/components/Esdoc/InheritedSummaryDoc.js

@@ -0,0 +1,70 @@
+/* eslint-disable react/prop-types */
+/* eslint-disable no-continue */
+/* eslint-disable no-restricted-syntax */
+/* eslint-disable react/no-array-index-key */
+/* eslint-disable no-underscore-dangle */
+import React, { useState } from 'react';
+import { _find } from './DocBuilderUtils';
+import SummaryDoc from './SummaryDoc';
+import DocLinkHTML from './DocLinkHTML';
+
+/**
+ * See InhertiedSummaryHTML component.
+ */
+function InheritedSummaryDoc({ longname, kind }) {
+  const [open, setOpen] = useState('closed');
+  const superDoc = _find({ longname })[0];
+
+  if (!superDoc) return null;
+
+  const toggle = () => {
+    if (open === 'closed') setOpen('opened');
+    else setOpen('closed');
+  };
+
+  const targetDocs = _find({
+    memberof: longname,
+    kind: kind ? [kind] : ['member', 'method', 'get', 'set'],
+  });
+
+  targetDocs.sort((a, b) => {
+    if (a.static !== b.static) return -(a.static - b.static);
+
+    let order = { get: 0, set: 0, member: 1, method: 2 };
+    if (order[a.kind] !== order[b.kind]) {
+      return order[a.kind] - order[b.kind];
+    }
+
+    order = { public: 0, protected: 1, private: 2 };
+    if (a.access !== b.access) return order[a.access] - order[b.access];
+
+    if (a.name !== b.name) return a.name < b.name ? -1 : 1;
+
+    order = { get: 0, set: 1, member: 2 };
+    return order[a.kind] - order[b.kind];
+  });
+
+  const title = (
+    <span
+      onClick={toggle}
+      onKeyPress={(evt) => {
+        if (evt.which === 13) {
+          toggle();
+        }
+      }}
+      role="button"
+      tabIndex="0"
+    >
+      <span className={`toggle ${open}`} /> From {superDoc.kind}{' '}
+      <DocLinkHTML longname={longname} text={superDoc.name} />
+    </span>
+  );
+  return (
+    <SummaryDoc
+      docs={targetDocs}
+      title={title}
+      style={{ display: open === 'opened' ? 'block' : 'none' }}
+    />
+  );
+}
+export default React.memo(InheritedSummaryDoc);

package/src/doc/components/Esdoc/InheritedSummaryHTML.js

@@ -0,0 +1,38 @@
+/* eslint-disable no-continue */
+/* eslint-disable no-restricted-syntax */
+/* eslint-disable react/no-array-index-key */
+/* eslint-disable no-underscore-dangle */
+import React from 'react';
+import InheritedSummaryDoc from './InheritedSummaryDoc';
+import { _find } from './DocBuilderUtils';
+
+/**
+ * build inherited method/member summary.
+ * https://github.com/esdoc/esdoc-plugins/blob/2de5022baa569785a189056a99acd1d7ca8284b7/esdoc-publish-html-plugin/src/Builder/ClassDocBuilder.js#L220
+ * @param {DocObject} doc - target class doc.
+ * @returns {string} html of inherited method/member from ancestor classes.
+ * @private
+ */
+const InheritedSummaryHTML = ({ doc, kind }) => {
+  if (['class', 'interface'].indexOf(doc.kind) === -1) return '';
+
+  const longnames = [
+    ...(doc._custom_extends_chains || []),
+    // ...doc.implements || [],
+    // ...doc._custom_indirect_implements || [],
+  ];
+
+  return longnames.map((longname, idx) => {
+    const superDoc = _find({ longname })[0];
+
+    if (!superDoc) return null;
+
+    return (
+      <React.Fragment key={idx}>
+        <InheritedSummaryDoc longname={longname} kind={kind} />
+        {idx !== longnames.length - 1 ? '\n' : ''}
+      </React.Fragment>
+    );
+  });
+};
+export default React.memo(InheritedSummaryHTML);