mobility-toolbox-js 2.0.0-beta.2 → 2.0.0-beta.8

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

@@ -0,0 +1,29 @@
+/* eslint-disable react/prop-types */
+import React from 'react';
+import DocLinkHTML from './DocLinkHTML';
+
+/**
+ * build mixin extends html.
+ * https://github.com/esdoc/esdoc-plugins/blob/2de5022baa569785a189056a99acd1d7ca8284b7/esdoc-publish-html-plugin/src/Builder/ClassDocBuilder.js#L134
+ * @param {DocObject} doc - target class doc.
+ * @return {string} mixin extends html.
+ */
+function MixinClassesHTML({ doc }) {
+  if (!doc.extends) return '';
+  if (doc.extends.length <= 1) return '';
+
+  return (
+    <div className="flat-list" data-ice="mixinExtends">
+      <h4>Mixin Extends:</h4>
+      <div>
+        {doc.extends.map((extend, idx) => (
+          <React.Fragment key={extend}>
+            <DocLinkHTML longname={extend} />{' '}
+            {idx !== doc.extends.length - 1 ? ', ' : ''}
+          </React.Fragment>
+        ))}
+      </div>
+    </div>
+  );
+}
+export default React.memo(MixinClassesHTML);

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

@@ -0,0 +1,112 @@
+/* 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 Anchor from './Anchor';
+import { _find, escapeURLHash } from './DocBuilderUtils';
+import DocLinkHTML from './DocLinkHTML';
+
+/**
+ * build common navigation output.
+ * https://github.com/esdoc/esdoc-plugins/blob/2de5022baa569785a189056a99acd1d7ca8284b7/esdoc-publish-html-plugin/src/Builder/DocBuilder.js#L177
+ * @return {IceCap} navigation output.
+ * @private
+ */
+function NavDoc() {
+  const kinds = ['class', 'function', 'variable']; // , 'typedef', 'external'];
+
+  // we display only public doc and not externals, feel free to reactivate them if you want.
+  const allDocs = _find({ kind: kinds }).filter((v) => v.access === 'public');
+
+  const kindOrder = {
+    class: 0,
+    interface: 1,
+    function: 2,
+    variable: 3,
+    typedef: 4,
+    external: 5,
+  };
+
+  // Add a typedef doc to have a link to main type def page
+  allDocs.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,
+  });
+
+  // see: IdentifiersDocBuilder#_buildIdentifierDoc
+  allDocs.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;
+  });
+  let lastDirPath = '.';
+
+  return (
+    <div>
+      <ul>
+        {allDocs.map((doc) => {
+          const filePath = doc.longname.split('~')[0].replace(/^.*?[/]/, '');
+          const dirPath = path.dirname(filePath);
+          const kind = doc.interface ? 'interface' : doc.kind;
+          const kindText = kind.charAt(0).toUpperCase();
+          const kindClass = `kind-${kind}`;
+          //   ice.load('name', this._buildDocLinkHTML(doc.longname));
+          //   ice.load('kind', kindText);
+          //   ice.attr('kind', 'class', kindClass);
+          //   ice.text('dirPath', dirPath);
+          //   ice.attr(
+          //     'dirPath',
+          //     'href',
+          //     `identifiers.html#${escapeURLHash(dirPath)}`,
+          //   );
+          //   ice.drop('dirPath', lastDirPath === dirPath);
+          const displayDir = lastDirPath !== dirPath;
+          lastDirPath = dirPath;
+          return (
+            <li data-ice="doc" key={doc.longname}>
+              {displayDir && (
+                <Anchor
+                  data-ice="dirPath"
+                  className="nav-dir-path"
+                  path={`/api/identifiers%20html#${escapeURLHash(dirPath)}`}
+                >
+                  {dirPath || 'api'}
+                </Anchor>
+              )}
+              <span data-ice="kind" className={kindClass}>
+                {kindText}
+              </span>
+              <span data-ice="name">
+                <DocLinkHTML longname={doc.longname} />
+              </span>
+            </li>
+          );
+        })}
+      </ul>
+    </div>
+  );
+}
+
+export default React.memo(NavDoc);

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

@@ -0,0 +1,44 @@
+/* eslint-disable react/prop-types */
+/* eslint-disable no-continue */
+/* eslint-disable no-restricted-syntax */
+/* eslint-disable no-underscore-dangle */
+import React from 'react';
+import { _findByName, _find } from './DocBuilderUtils';
+import DocLinkHTML from './DocLinkHTML';
+
+/**
+ * build method of ancestor class link html.
+ * https://github.com/esdoc/esdoc-plugins/blob/2de5022baa569785a189056a99acd1d7ca8284b7/esdoc-publish-html-plugin/src/Builder/DocBuilder.js#L952
+ * @param {DocObject} doc - target doc object.
+ * @returns {string} html link. if doc does not override ancestor method, returns empty.
+ * @private
+ */
+function OverrideMethod({ doc }) {
+  const parentDoc = _findByName(doc.memberof)[0];
+  if (!parentDoc) return '';
+  if (!parentDoc._custom_extends_chains) return '';
+
+  const chains = [...parentDoc._custom_extends_chains].reverse();
+  for (const longname of chains) {
+    const superClassDoc = _findByName(longname)[0];
+    if (!superClassDoc) continue;
+
+    const superMethodDoc = _find({
+      name: doc.name,
+      memberof: superClassDoc.longname,
+    })[0];
+    if (!superMethodDoc) continue;
+
+    return (
+      <DocLinkHTML
+        longname={superMethodDoc.longname}
+        text={`${superClassDoc.name}#${superMethodDoc.name}`}
+        inner
+      />
+    );
+  }
+
+  return null;
+}
+
+export default React.memo(OverrideMethod);

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

@@ -0,0 +1,35 @@
+/* eslint-disable no-continue */
+/* eslint-disable no-restricted-syntax */
+/* eslint-disable no-underscore-dangle */
+import React from 'react';
+import { _findByName, _find } from './DocBuilderUtils';
+/**
+ * build method of ancestor class description.
+ * https://github.com/esdoc/esdoc-plugins/blob/2de5022baa569785a189056a99acd1d7ca8284b7/esdoc-publish-html-plugin/src/Builder/DocBuilder.js#L977
+ * @param {DocObject} doc - target doc object.
+ * @returns {string} description. if doc does not override ancestor method, returns empty.
+ * @private
+ */
+const OverrideMethodDescription = ({ doc }) => {
+  const parentDoc = _findByName(doc.memberof)[0];
+  if (!parentDoc) return '';
+  if (!parentDoc._custom_extends_chains) return '';
+
+  const chains = [...parentDoc._custom_extends_chains].reverse();
+  for (const longname of chains) {
+    const superClassDoc = _findByName(longname)[0];
+    if (!superClassDoc) continue;
+
+    const superMethodDoc = _find({
+      name: doc.name,
+      memberof: superClassDoc.longname,
+    })[0];
+    if (!superMethodDoc) continue;
+
+    if (superMethodDoc.description) return superMethodDoc.description;
+  }
+
+  return '';
+};
+
+export default React.memo(OverrideMethodDescription);

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

@@ -0,0 +1,89 @@
+/* eslint-disable react/no-array-index-key */
+/* eslint-disable react/prop-types */
+import React from 'react';
+import Markdown from 'react-markdown';
+import TypeDocLinkHTML from './TypeDocLinkHTML';
+
+/**
+ * build properties output.
+ * https://github.com/esdoc/esdoc-plugins/blob/2de5022baa569785a189056a99acd1d7ca8284b7/esdoc-publish-html-plugin/src/Builder/DocBuilder.js#L870
+ * @param {ParsedParam[]} [properties=[]] - properties in doc object.
+ * @param {string} title - output title.
+ * @return {IceCap} built properties output.
+ * @private
+ */
+function Properties({ properties = [], title = 'Properties:' }) {
+  return (
+    <div data-ice="properties">
+      <h4 data-ice="title">{title}</h4>
+      <table className="params">
+        <thead>
+          <tr>
+            <td>Name</td>
+            <td>Type</td>
+            <td>Attribute</td>
+            <td>Description</td>
+          </tr>
+        </thead>
+        <tbody>
+          {properties.map((prop) => {
+            // appendix
+            const appendix = [];
+            if (prop.optional) {
+              appendix.push(<li>optional</li>);
+            }
+            if ('defaultValue' in prop) {
+              appendix.push(<li>default: {prop.defaultValue}</li>);
+            }
+            if (typeof prop.nullable === 'boolean') {
+              appendix.push(<li>nullable: {prop.nullable}</li>);
+            }
+            return (
+              <tr
+                key={prop.name}
+                data-ice="property"
+                data-depth={prop.name.split('.').length - 1}
+              >
+                <td
+                  data-ice="name"
+                  className="code"
+                  data-depth={prop.name.split('.').length - 1}
+                >
+                  {prop.name}
+                </td>
+                <td data-ice="type" className="code">
+                  {prop.types.map((typeName, idx) => {
+                    return (
+                      <React.Fragment key={idx}>
+                        <TypeDocLinkHTML typeName={typeName} />
+                        {idx !== prop.types.length - 1 ? ' | ' : ''}
+                      </React.Fragment>
+                    );
+                  })}
+                </td>
+                <td data-ice="appendix">
+                  {!!appendix.length && (
+                    <ul>
+                      {appendix.map((comp, idx) => {
+                        return (
+                          <React.Fragment key={idx}>
+                            {comp}
+                            {idx !== appendix.length - 1 ? '\n' : ''}
+                          </React.Fragment>
+                        );
+                      })}
+                    </ul>
+                  )}
+                </td>
+                <td data-ice="description">
+                  <Markdown>{prop.description}</Markdown>
+                </td>
+              </tr>
+            );
+          })}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+export default React.memo(Properties);

package/src/doc/components/Esdoc/README.md

@@ -0,0 +1,45 @@
+# react-esdoc
+
+This folder contains an implementation of the rendering of [esdoc-publish-html-plugin](https://github.com/esdoc/esdoc-plugins/blob/2de5022baa569785a189056a99acd1d7ca8284b7/esdoc-publish-html-plugin).
+
+Every components in this folder is an implementation of a `_buildXXX` function in [Builder folder of the plugin](https://github.com/esdoc/esdoc-plugins/tree/2de5022baa569785a189056a99acd1d7ca8284b7/esdoc-publish-html-plugin/src/Builder)
+In the documentation of the component you can find the link to the function it implements.
+
+The original css from [esdoc-publish-html-plugin](https://github.com/esdoc/esdoc-plugins/blob/2de5022baa569785a189056a99acd1d7ca8284b7/esdoc-publish-html-plugin) is used. See `./css` folder.
+
+## How does it work
+
+The [esdoc-publish-html-plugin](https://github.com/esdoc/esdoc-plugins/blob/2de5022baa569785a189056a99acd1d7ca8284b7/esdoc-publish-html-plugin) creates an `index.json` in `apidoc/index.json` when we run `yarn apidoc`.
+
+The `yarn apidoc` task copy automatically this `index.json` in this folder.
+
+This json is loaded in `./DocBuilderUtils.js` then a in memory [taffy](http://taffydb.com/) database is loaded with its content.
+This database is only used to facilitate the retrievment of data from the `ìndex.json` content.
+
+## Components
+
+Only 4 components must be used directly:
+
+- Esdoc : The documentation layout.
+- EsdocContent : The class/type/function documentation display.
+- EsdocNavigation: The documentation navigation tool.
+- EsdocSearch: The documentation search box.
+
+## TODO
+
+List of functionalities not implemented because we don't use it :
+
+- Tests
+- Decorators
+- TODO
+
+## Improvments
+
+- Pass the index.json content as a parameter.
+- Configure the replacement of '.' by '%20' in url to make it work with react-router.
+- Configure the base url, currently /api/ is append to all links except source links.
+- Configure the github url, currently github.com/mobility-toolbox-js/... is append to all sources links.
+- Create an esdoc plugin to generate only the index.json file, it should be easy using [esdoc-publish-html-plugin](https://github.com/esdoc/esdoc-plugins/blob/2de5022baa569785a189056a99acd1d7ca8284b7/esdoc-publish-html-plugin) code.
+- Convert css to scss.
+- Reactivate all eslint rules.
+- Reactivate all stylelint rules.

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

@@ -0,0 +1,123 @@
+/* eslint-disable react/no-array-index-key */
+/* eslint-disable no-continue */
+/* eslint-disable no-restricted-syntax */
+import React from 'react';
+import TypeDocLinkHTML from './TypeDocLinkHTML';
+
+/**
+ * build identifier signature html.
+ * https://github.com/esdoc/esdoc-plugins/blob/2de5022baa569785a189056a99acd1d7ca8284b7/esdoc-publish-html-plugin/src/Builder/DocBuilder.js#L813
+ * @param {DocObject} doc - target doc object.
+ * @returns {string} signature html.
+ * @private
+ */
+const SignatureHTML = ({ doc }) => {
+  // call signature
+  const callSignatures = [];
+  if (doc.params) {
+    for (const param of doc.params) {
+      const paramName = param.name;
+      if (paramName.indexOf('.') !== -1) continue; // for object property
+      if (paramName.indexOf('[') !== -1) continue; // for array property
+
+      const types = [];
+      for (const typeName of param.types) {
+        types.push(<TypeDocLinkHTML typeName={typeName} />);
+      }
+
+      callSignatures.push(
+        <>
+          {`${paramName}: `}
+          {types.map((comp, idx) => {
+            return (
+              <React.Fragment key={idx}>
+                {comp}
+                {idx !== types.length - 1 ? ' | ' : ''}
+              </React.Fragment>
+            );
+          })}
+        </>,
+      );
+    }
+  }
+
+  // return signature
+  const returnSignatures = [];
+  if (doc.return) {
+    for (const typeName of doc.return.types) {
+      returnSignatures.push(<TypeDocLinkHTML typeName={typeName} />);
+    }
+  }
+
+  // type signature
+  let typeSignatures = [];
+  if (doc.type) {
+    for (const typeName of doc.type.types) {
+      typeSignatures.push(<TypeDocLinkHTML typeName={typeName} />);
+    }
+  }
+
+  // callback is not need type. because type is always function.
+  if (doc.kind === 'function') {
+    typeSignatures = [];
+  }
+
+  let html = '';
+  const hasMoreThan1Param = callSignatures.length > 1;
+  if (callSignatures.length) {
+    html = (
+      <>
+        (
+        {callSignatures.map((comp, idx) => {
+          return (
+            <React.Fragment key={idx}>
+              {hasMoreThan1Param && <br />}
+              <span style={{ paddingLeft: hasMoreThan1Param ? 20 : 0 }}>
+                {comp}
+                {idx !== callSignatures.length - 1 ? ', ' : ''}
+              </span>
+              {hasMoreThan1Param && idx === callSignatures.length - 1 && <br />}
+            </React.Fragment>
+          );
+        })}
+        )
+      </>
+    );
+  } else if (['function', 'method', 'constructor'].includes(doc.kind)) {
+    html = '()';
+  }
+  if (returnSignatures.length)
+    html = (
+      <>
+        {html}
+        {`: `}
+        {returnSignatures.map((comp, idx) => {
+          return (
+            <React.Fragment key={idx}>
+              {comp}
+              {idx !== returnSignatures.length - 1 ? ' | ' : ''}
+            </React.Fragment>
+          );
+        })}
+      </>
+    );
+  if (typeSignatures.length)
+    html = (
+      <>
+        {html}
+        {`: `}
+        {typeSignatures.map((comp, idx) => {
+          return (
+            <React.Fragment key={idx}>
+              {comp}
+              {idx !== typeSignatures.length - 1 ? ' | ' : ''}
+            </React.Fragment>
+          );
+        })}
+      </>
+    );
+
+  return html;
+};
+
+export default React.memo(SignatureHTML);

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

@@ -0,0 +1,31 @@
+/* eslint-disable no-continue */
+/* eslint-disable no-restricted-syntax */
+/* eslint-disable no-underscore-dangle */
+/* eslint-disable react/prop-types */
+import React from 'react';
+import SummaryHTML from './SummaryHTML';
+import DetailHTML from './DetailHTML';
+
+/**
+ * build single output.
+ * https://github.com/esdoc/esdoc-plugins/blob/2de5022baa569785a189056a99acd1d7ca8284b7/esdoc-publish-html-plugin/src/Builder/SingleDocBuilder.js#L29
+ * @param {string} kind - target kind property.
+ * @returns {string} html of single output
+ * @private
+ */
+function SingleDoc({ kind }) {
+  const title = kind.replace(/^(\w)/, (c) => c.toUpperCase());
+  return (
+    <>
+      <h1 data-ice="title">{title}</h1>
+      <div data-ice="summaries">
+        <SummaryHTML doc={null} kind={kind} title="Summary" />
+      </div>
+      <div data-ice="details">
+        <DetailHTML doc={null} kind={kind} title="" />
+      </div>
+    </>
+  );
+}
+
+export default React.memo(SingleDoc);

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

@@ -0,0 +1,160 @@
+/* eslint-disable react/prop-types */
+/* eslint-disable react/no-array-index-key */
+import React, { useMemo } from 'react';
+import Markdown from 'react-markdown';
+import DocLinkHTML from './DocLinkHTML';
+import SignatureHTML from './SignatureHTML';
+import ExperimentalHTML from './ExperimentalHTML';
+import DeprecatedHTML from './DeprecatedHTML';
+
+const showInheritedHref = (memberof, parentMemberOf) => {
+  const name = memberof.split('~');
+  if (name[0] === parentMemberOf) {
+    return null;
+  }
+  return (
+    <>
+      Inherited from:{' '}
+      <a href={`/api/class/${memberof.replace('.', '%20')}%20html`}>
+        {name.length && name[1]}
+      </a>
+    </>
+  );
+};
+/**
+ * build summary output html by docs.
+ * https://github.com/esdoc/esdoc-plugins/blob/2de5022baa569785a189056a99acd1d7ca8284b7/esdoc-publish-html-plugin/src/Builder/DocBuilder.js#L294
+ * @param {DocObject[]} docs - target docs.
+ * @param {string} title - summary title.
+ * @param {boolean} innerLink - if true, link in summary is inner link.
+ * @param {boolean} kindIcon - use kind icon.
+ * @param {string} memberof - memberof of the parent doc.
+ * @return {IceCap} summary output.
+ * @protected
+ */
+function SummaryDoc({
+  docs,
+  // eslint-disable-next-line no-unused-vars
+  title,
+  innerLink = false,
+  kindIcon = false,
+  memberof,
+  style,
+}) {
+  const showInherited = useMemo(() => {
+    if (docs.length === 0) return null;
+    return ['member', 'method'].includes(docs[0].kind);
+  }, [docs]);
+
+  if (docs.length === 0) return null;
+
+  return (
+    <table className="summary" data-ice="summary">
+      {/* <thead>
+        <tr>
+          <td data-ice="title" colSpan="2">
+            {title}
+          </td>
+        </tr>
+      </thead> */}
+      <tbody style={style}>
+        {docs
+          .filter((doc) => doc.access === 'public')
+          .map((doc, idx) => {
+            const kindKindIcon = doc.interface ? 'interface' : doc.kind;
+            return (
+              <tr data-ice="target" key={idx}>
+                {/* Hide the access (public) column */}
+                {/*
+              <td>
+                <span className="access" data-ice="access">
+                  {doc.access}
+                </span>
+                {staticc && <span data-ice="static">{staticc}</span>}
+                {kind && (
+                  <span className="kind" data-ice="kind">
+                    {kind}
+                  </span>
+                )}
+                <span className="abstract" data-ice="abstract">
+                  {doc.abstract ? 'abstract' : ''}
+                </span>
+                <span className="override" data-ice="override" />
+              </td>
+              */}
+                <td>
+                  <div>
+                    <p>
+                      {kindIcon && (
+                        <span
+                          data-ice="kind-icon"
+                          className={`kind-${kindKindIcon}`}
+                        >
+                          {kindKindIcon.charAt(0).toUpperCase()}
+                        </span>
+                      )}
+                      <span data-ice="async">{doc.async ? 'async' : ''}</span>
+                      <span data-ice="generator">
+                        {doc.generator ? '*' : ''}
+                      </span>
+                      <span className="code" data-ice="name">
+                        <DocLinkHTML
+                          longname={doc.longname}
+                          text={
+                            doc.kind === 'constructor'
+                              ? `new ${
+                                  doc.longname.match(/~([^)]+)#constructor/)[1]
+                                }`
+                              : null
+                          }
+                          inner={innerLink}
+                          kind={doc.kind}
+                        />
+                      </span>
+                      <span className="code" data-ice="signature">
+                        <SignatureHTML doc={doc} />
+                      </span>
+                    </p>
+                  </div>
+                </td>
+                <td>
+                  <div>
+                    <div className="deprecated" data-ice="deprecated">
+                      <DeprecatedHTML doc={doc} />
+                    </div>
+                    <div className="experimental" data-ice="experimental">
+                      <ExperimentalHTML doc={doc} />
+                    </div>
+
+                    <div data-ice="description">
+                      <Markdown>{doc.description}</Markdown>
+                    </div>
+                    <div data-ice="inherited">
+                      {showInherited
+                        ? showInheritedHref(doc.memberof, memberof)
+                        : null}
+                    </div>
+                  </div>
+                </td>
+                {doc.version || doc.since ? (
+                  <td>
+                    {doc.version && (
+                      <span className="version" data-ice="version">
+                        {doc.version}{' '}
+                      </span>
+                    )}
+                    {doc.since && (
+                      <span className="since" data-ice="since">
+                        {doc.since}{' '}
+                      </span>
+                    )}
+                  </td>
+                ) : null}
+              </tr>
+            );
+          })}
+      </tbody>
+    </table>
+  );
+}
+export default React.memo(SummaryDoc);