[docs] Fix /api client-side routing (#23586)

mui · Nov 18, 2020 · 75dc225 · 75dc225
1 parent 6859c13
commit 75dc225
Show file tree

Hide file tree

Showing 8 changed files with 97 additions and 61 deletions.
diff --git a/docs/next.config.js b/docs/next.config.js
@@ -195,9 +195,6 @@ module.exports = {
   },
   reactStrictMode: reactMode === 'legacy-strict',
   async rewrites() {
-    return [
-      { source: `/:lang(${LANGUAGES.join('|')})?/:rest*`, destination: '/:rest*' },
-      { source: '/api/:rest*', destination: '/api-docs/:rest*' },
-    ];
+    return [{ source: `/:lang(${LANGUAGES.join('|')})?/:rest*`, destination: '/:rest*' }];
   },
 };
diff --git a/docs/scripts/i18n.js b/docs/scripts/i18n.js
@@ -1,4 +1,3 @@
-/* eslint-disable no-console */
 import path from 'path';
 import fse from 'fs-extra';
 import { pageToTitle } from 'docs/src/modules/utils/helpers';
@@ -7,39 +6,37 @@ import pages from 'docs/src/pages';
 const EXCLUDES = ['/api', '/blog'];
 
 async function run() {
-  try {
-    const translationsFilename = path.join(__dirname, '../translations/translations.json');
-    const translationsFile = await fse.readFile(translationsFilename, 'utf8');
-    const output = JSON.parse(translationsFile);
-    output.pages = {};
-
-    const traverse = (pages2) => {
-      pages2.forEach((page) => {
-        if (
-          (page.pathname !== '/' && page.pathname === '/api-docs') ||
-          !EXCLUDES.some((exclude) => page.pathname.includes(exclude))
-        ) {
-          const title = pageToTitle(page);
-
-          if (title) {
-            const pathname = page.subheader || page.pathname;
-            output.pages[pathname] = title;
-          }
+  const translationsFilename = path.join(__dirname, '../translations/translations.json');
+  const translationsFile = await fse.readFile(translationsFilename, 'utf8');
+  const output = JSON.parse(translationsFile);
+  output.pages = {};
+
+  const traverse = (pages2) => {
+    pages2.forEach((page) => {
+      if (
+        (page.pathname !== '/' && page.pathname === '/api-docs') ||
+        !EXCLUDES.some((exclude) => page.pathname.includes(exclude))
+      ) {
+        const title = pageToTitle(page);
+
+        if (title) {
+          const pathname = page.subheader || page.pathname;
+          output.pages[pathname] = title;
         }
+      }
 
-        if (page.children) {
-          traverse(page.children);
-        }
-      });
-    };
+      if (page.children) {
+        traverse(page.children);
+      }
+    });
+  };
 
-    traverse(pages);
+  traverse(pages);
 
-    await fse.writeFile(translationsFilename, `${JSON.stringify(output, null, 2)}\n`);
-  } catch (err) {
-    console.log(err);
-    throw err;
-  }
+  await fse.writeFile(translationsFilename, `${JSON.stringify(output, null, 2)}\n`);
 }
 
-run();
+run().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
diff --git a/docs/src/modules/components/AppDrawer.js b/docs/src/modules/components/AppDrawer.js
@@ -92,7 +92,13 @@ function renderNavItems(options) {
   );
 }
 
-function reduceChildRoutes({ onClose, activePage, items, page, depth, t }) {
+/**
+ * @param {object} context
+ * @param {import('docs/src/pages').MuiPage} context.page
+ */
+function reduceChildRoutes(context) {
+  const { onClose, activePage, items, depth, t } = context;
+  let { page } = context;
   if (page.displayNav === false) {
     return items;
   }

diff --git a/docs/src/modules/components/Link.js b/docs/src/modules/components/Link.js
@@ -28,25 +28,24 @@ function Link(props) {
   const {
     activeClassName = 'active',
     className: classNameProps,
-    href: routerHref,
+    href,
     innerRef,
     naked,
     role: roleProp,
+    as: asProp = href,
     ...other
   } = props;
 
-  // apply nextjs rewrites
-  const href = routerHref.replace(/\/api-docs\/(.*)/, '/api/$1');
-
   const router = useRouter();
 
   const userLanguage = useUserLanguage();
   const className = clsx(classNameProps, {
-    [activeClassName]: router.pathname === routerHref && activeClassName,
+    [activeClassName]: router.pathname === href && activeClassName,
   });
 
+  let linkAs = asProp;
   if (userLanguage !== 'en' && href.indexOf('/') === 0 && href.indexOf('/blog') !== 0) {
-    other.as = `/${userLanguage}${href}`;
+    linkAs = `/${userLanguage}${linkAs}`;
   }
 
   // catch role passed from ButtonBase. This is definitely a link
@@ -63,11 +62,21 @@ function Link(props) {
   }
 
   if (naked) {
-    return <NextComposed className={className} href={href} ref={innerRef} role={role} {...other} />;
+    return (
+      <NextComposed
+        as={linkAs}
+        className={className}
+        href={href}
+        ref={innerRef}
+        role={role}
+        {...other}
+      />
+    );
   }
 
   return (
     <MuiLink
+      as={linkAs}
       component={NextComposed}
       className={className}
       href={href}

diff --git a/docs/src/modules/components/PageContext.js b/docs/src/modules/components/PageContext.js
@@ -1,14 +1,9 @@
 import * as React from 'react';
 
-// The default value is never and should never be used.
-// It's here to improve DX by enabling autocompletion for editors supporting TypeScript.
-const PageContext = React.createContext({
-  activePage: {
-    pathname: '',
-  },
-  pages: [],
-  versions: [],
-});
+/**
+ * @type {React.Context<{ activePage: { pathname: string }, pages: Array<import('docs/src/pages').MuiPage>, versions: unknown[] }>}
+ */
+const PageContext = React.createContext();
 
 if (process.env.NODE_ENV !== 'production') {
   PageContext.displayName = 'PageContext';

diff --git a/docs/src/modules/utils/find.js b/docs/src/modules/utils/find.js
@@ -79,9 +79,21 @@ function findComponents(directory, components = []) {
 const jsRegex = /\.js$/;
 const blackList = ['/.eslintrc', '/_document', '/_app'];
 
-// Returns the Next.js pages available in a nested format.
-// The output is in the next.js format.
-// Each pathname is a route you can navigate to.
+/**
+ * @typedef {object} NextJSPage
+ * @property {string} pathname
+ * @property {NextJSPage[]} [children]
+ */
+
+/**
+ * Returns the Next.js pages available in a nested format.
+ * The output is in the next.js format.
+ * Each pathname is a route you can navigate to.
+ * @param {{ front: true }} [options]
+ * @param {string} [directory]
+ * @param {NextJSPage[]} pages
+ * @returns {NextJSPage[]}
+ */
 function findPages(
   options = {},
   directory = path.resolve(__dirname, '../../../pages'),

diff --git a/docs/src/pages.js → docs/src/pages.ts b/docs/src/pages.js → docs/src/pages.ts
@@ -1,6 +1,22 @@
 import findPages from /* preval */ 'docs/src/modules/utils/findPages';
 
-const pages = [
+export interface MuiPage {
+  pathname: string;
+  children?: MuiPage[];
+  disableDrawer?: boolean;
+  displayNav?: boolean;
+  /**
+   * Props spread to the Link component
+   */
+  linkProps?: Record<string, unknown>;
+  subheader?: string;
+  /**
+   * Overrides the default page title.
+   */
+  title?: string;
+}
+
+const pages: MuiPage[] = [
   {
     pathname: '/getting-started',
     children: [
@@ -168,11 +184,15 @@ const pages = [
     title: 'Component API',
     pathname: '/api-docs',
     children: [
-      ...findPages[0].children,
+      ...findPages[0].children!,
       ...[{ pathname: '/api-docs/data-grid' }, { pathname: '/api-docs/x-grid' }],
-    ].sort((a, b) =>
-      a.pathname.replace('/api-docs/', '').localeCompare(b.pathname.replace('/api-docs/', '')),
-    ),
+    ]
+      .sort((a, b) =>
+        a.pathname.replace('/api-docs/', '').localeCompare(b.pathname.replace('/api-docs/', '')),
+      )
+      .map((page) => {
+        return { ...page, linkProps: { as: page.pathname.replace(/^\/api-docs/, '/api') } };
+      }),
   },
   {
     pathname: '/system',

diff --git a/package.json b/package.json
@@ -18,7 +18,7 @@
     "docs:icons": "yarn workspace docs icons",
     "docs:size-why": "cross-env DOCS_STATS_ENABLED=true yarn docs:build",
     "docs:start": "yarn workspace docs start",
-    "docs:i18n": "cross-env BABEL_ENV=test babel-node ./docs/scripts/i18n.js",
+    "docs:i18n": "cross-env BABEL_ENV=test babel-node --extensions \".tsx,.ts,.js\" ./docs/scripts/i18n.js",
     "docs:typescript": "yarn docs:typescript:formatted --watch",
     "docs:typescript:check": "yarn workspace docs typescript",
     "docs:typescript:formatted": "cross-env BABEL_ENV=test babel-node --extensions \".tsx,.ts,.js\" ./docs/scripts/formattedTSDemos",