@docusaurus/theme-classic 2.0.0-beta.1ec2c95e3 → 2.0.0-beta.21

package/lib/theme/PaginatorNavLink/index.js

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React from 'react';
+import clsx from 'clsx';
+import Link from '@docusaurus/Link';
+export default function PaginatorNavLink(props) {
+  const {permalink, title, subLabel, isNext} = props;
+  return (
+    <Link
+      className={clsx(
+        'pagination-nav__link',
+        isNext ? 'pagination-nav__link--next' : 'pagination-nav__link--prev',
+      )}
+      to={permalink}>
+      {subLabel && <div className="pagination-nav__sublabel">{subLabel}</div>}
+      <div className="pagination-nav__label">{title}</div>
+    </Link>
+  );
+}

package/lib/theme/SearchBar.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export { default } from '@docusaurus/Noop';

package/lib/theme/SearchBar.js

@@ -1,15 +1,11 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-Object.defineProperty(exports, "default", {
-  enumerable: true,
-  get: function () {
-    return _Noop.default;
-  }
-});
-
-var _Noop = _interopRequireDefault(require("@docusaurus/Noop"));
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+// By default, the classic theme does not provide any SearchBar implementation
+// If you swizzled this, it is your responsibility to provide an implementation
+// Tip: swizzle the SearchBar from the Algolia theme for inspiration:
+// npm run swizzle @docusaurus/theme-search-algolia SearchBar
+export {default} from '@docusaurus/Noop';

package/lib/theme/SearchMetadata/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/// <reference types="react" />
+import type { Props } from '@theme/SearchMetadata';
+export default function SearchMetadata({ locale, version, tag, }: Props): JSX.Element;

package/lib/theme/SearchMetadata/index.js

@@ -0,0 +1,34 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React from 'react';
+import Head from '@docusaurus/Head';
+// Note: we bias toward using Algolia metadata on purpose
+// Not doing so leads to confusion in the community,
+// as it requires to first crawl the site with the Algolia plugin enabled first
+// - https://github.com/facebook/docusaurus/issues/6693
+// - https://github.com/facebook/docusaurus/issues/4555
+export default function SearchMetadata({locale, version, tag}) {
+  // Seems safe to consider here the locale is the language, as the existing
+  // docsearch:language filter is afaik a regular string-based filter
+  const language = locale;
+  return (
+    <Head>
+      {/*
+        Docusaurus metadata, used by third-party search plugin
+        See https://github.com/cmfcmf/docusaurus-search-local/issues/99
+        */}
+      {locale && <meta name="docusaurus_locale" content={locale} />}
+      {version && <meta name="docusaurus_version" content={version} />}
+      {tag && <meta name="docusaurus_tag" content={tag} />}
+
+      {/* Algolia DocSearch metadata */}
+      {language && <meta name="docsearch:language" content={language} />}
+      {version && <meta name="docsearch:version" content={version} />}
+      {tag && <meta name="docsearch:docusaurus_tag" content={tag} />}
+    </Head>
+  );
+}

package/lib/theme/SiteMetadata/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/// <reference types="react" />
+export default function SiteMetadata(): JSX.Element;

package/lib/theme/SiteMetadata/index.js

@@ -0,0 +1,117 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React from 'react';
+import Head from '@docusaurus/Head';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import {
+  PageMetadata,
+  DEFAULT_SEARCH_TAG,
+  useAlternatePageUtils,
+  useThemeConfig,
+  keyboardFocusedClassName,
+} from '@docusaurus/theme-common';
+import {useLocation} from '@docusaurus/router';
+import SearchMetadata from '@theme/SearchMetadata';
+// TODO move to SiteMetadataDefaults or theme-common ?
+// Useful for i18n/SEO
+// See https://developers.google.com/search/docs/advanced/crawling/localized-versions
+// See https://github.com/facebook/docusaurus/issues/3317
+function AlternateLangHeaders() {
+  const {
+    i18n: {defaultLocale, localeConfigs},
+  } = useDocusaurusContext();
+  const alternatePageUtils = useAlternatePageUtils();
+  // Note: it is fine to use both "x-default" and "en" to target the same url
+  // See https://www.searchviu.com/en/multiple-hreflang-tags-one-url/
+  return (
+    <Head>
+      {Object.entries(localeConfigs).map(([locale, {htmlLang}]) => (
+        <link
+          key={locale}
+          rel="alternate"
+          href={alternatePageUtils.createUrl({
+            locale,
+            fullyQualified: true,
+          })}
+          hrefLang={htmlLang}
+        />
+      ))}
+      <link
+        rel="alternate"
+        href={alternatePageUtils.createUrl({
+          locale: defaultLocale,
+          fullyQualified: true,
+        })}
+        hrefLang="x-default"
+      />
+    </Head>
+  );
+}
+// Default canonical url inferred from current page location pathname
+function useDefaultCanonicalUrl() {
+  const {
+    siteConfig: {url: siteUrl},
+  } = useDocusaurusContext();
+  const {pathname} = useLocation();
+  return siteUrl + useBaseUrl(pathname);
+}
+// TODO move to SiteMetadataDefaults or theme-common ?
+function CanonicalUrlHeaders({permalink}) {
+  const {
+    siteConfig: {url: siteUrl},
+  } = useDocusaurusContext();
+  const defaultCanonicalUrl = useDefaultCanonicalUrl();
+  const canonicalUrl = permalink
+    ? `${siteUrl}${permalink}`
+    : defaultCanonicalUrl;
+  return (
+    <Head>
+      <meta property="og:url" content={canonicalUrl} />
+      <link rel="canonical" href={canonicalUrl} />
+    </Head>
+  );
+}
+export default function SiteMetadata() {
+  const {
+    i18n: {currentLocale},
+  } = useDocusaurusContext();
+  // TODO maybe move these 2 themeConfig to siteConfig?
+  // These seems useful for other themes as well
+  const {metadata, image: defaultImage} = useThemeConfig();
+  return (
+    <>
+      <Head>
+        <meta name="twitter:card" content="summary_large_image" />
+        {/* The keyboard focus class name need to be applied when SSR so links
+        are outlined when JS is disabled */}
+        <body className={keyboardFocusedClassName} />
+      </Head>
+
+      {defaultImage && <PageMetadata image={defaultImage} />}
+
+      <CanonicalUrlHeaders />
+
+      <AlternateLangHeaders />
+
+      <SearchMetadata tag={DEFAULT_SEARCH_TAG} locale={currentLocale} />
+
+      {/*
+          It's important to have an additional <Head> element here, as it allows
+          react-helmet to override default metadata values set in previous <Head>
+          like "twitter:card". In same Head, the same meta would appear twice
+          instead of overriding.
+        */}
+      <Head>
+        {/* Yes, "metadatum" is the grammatically correct term */}
+        {metadata.map((metadatum, i) => (
+          <meta key={i} {...metadatum} />
+        ))}
+      </Head>
+    </>
+  );
+}

package/lib/theme/SkipToContent/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/// <reference types="react" />
+export default function SkipToContent(): JSX.Element;

package/lib/theme/SkipToContent/index.js

@@ -1,71 +1,25 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = void 0;
-
-var _react = _interopRequireWildcard(require("react"));
-
-var _router = require("@docusaurus/router");
-
-var _Translate = _interopRequireDefault(require("@docusaurus/Translate"));
-
-var _themeCommon = require("@docusaurus/theme-common");
-
-var _stylesModule = _interopRequireDefault(require("./styles.module.css"));
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
-
-function _getRequireWildcardCache(nodeInterop) { if (typeof WeakMap !== "function") return null; var cacheBabelInterop = new WeakMap(); var cacheNodeInterop = new WeakMap(); return (_getRequireWildcardCache = function (nodeInterop) { return nodeInterop ? cacheNodeInterop : cacheBabelInterop; })(nodeInterop); }
-
-function _interopRequireWildcard(obj, nodeInterop) { if (!nodeInterop && obj && obj.__esModule) { return obj; } if (obj === null || typeof obj !== "object" && typeof obj !== "function") { return { default: obj }; } var cache = _getRequireWildcardCache(nodeInterop); if (cache && cache.has(obj)) { return cache.get(obj); } var newObj = {}; var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var key in obj) { if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) { var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null; if (desc && (desc.get || desc.set)) { Object.defineProperty(newObj, key, desc); } else { newObj[key] = obj[key]; } } } newObj.default = obj; if (cache) { cache.set(obj, newObj); } return newObj; }
-
 /**
  * Copyright (c) Facebook, Inc. and its affiliates.
  *
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-function programmaticFocus(el) {
-  el.setAttribute('tabindex', '-1');
-  el.focus();
-  el.removeAttribute('tabindex');
-}
-
-function SkipToContent() {
-  const containerRef = (0, _react.useRef)(null);
-  const {
-    action
-  } = (0, _router.useHistory)();
-
-  const handleSkip = e => {
-    e.preventDefault();
-    const targetElement = document.querySelector('main:first-of-type') || document.querySelector('.main-wrapper');
-
-    if (targetElement) {
-      programmaticFocus(targetElement);
-    }
-  };
-
-  (0, _themeCommon.useLocationChange)(({
-    location
-  }) => {
-    if (containerRef.current && !location.hash && action !== 'POP') {
-      programmaticFocus(containerRef.current);
-    }
-  });
-  return <div ref={containerRef}>
-      {
-      /* eslint-disable-next-line jsx-a11y/anchor-is-valid */
-    }
-      <a href="#" className={_stylesModule.default.skipToContent} onClick={handleSkip}>
-        <_Translate.default id="theme.common.skipToMainContent" description="The skip to content label used for accessibility, allowing to rapidly navigate to main content with keyboard tab/enter navigation">
+import React from 'react';
+import Translate from '@docusaurus/Translate';
+import {useSkipToContent} from '@docusaurus/theme-common';
+import styles from './styles.module.css';
+export default function SkipToContent() {
+  const {containerRef, handleSkip} = useSkipToContent();
+  return (
+    <div ref={containerRef} role="region">
+      {/* eslint-disable-next-line jsx-a11y/anchor-is-valid */}
+      <a href="#" className={styles.skipToContent} onClick={handleSkip}>
+        <Translate
+          id="theme.common.skipToMainContent"
+          description="The skip to content label used for accessibility, allowing to rapidly navigate to main content with keyboard tab/enter navigation">
           Skip to main content
-        </_Translate.default>
+        </Translate>
       </a>
-    </div>;
+    </div>
+  );
 }
-
-var _default = SkipToContent;
-exports.default = _default;

package/lib/theme/SkipToContent/styles.module.css

@@ -1,3 +1,10 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
 .skipToContent {
   position: fixed;
   top: 1rem;

package/lib/theme/TOC/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/// <reference types="react" />
+import type { Props } from '@theme/TOC';
+export default function TOC({ className, ...props }: Props): JSX.Element;

package/lib/theme/TOC/index.js

@@ -1,59 +1,25 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = void 0;
-
-var _react = _interopRequireDefault(require("react"));
-
-var _clsx = _interopRequireDefault(require("clsx"));
-
-var _useTOCHighlight = _interopRequireDefault(require("@theme/hooks/useTOCHighlight"));
-
-var _stylesModule = _interopRequireDefault(require("./styles.module.css"));
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
-
 /**
  * Copyright (c) Facebook, Inc. and its affiliates.
  *
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-const LINK_CLASS_NAME = 'table-of-contents__link';
-const ACTIVE_LINK_CLASS_NAME = 'table-of-contents__link--active';
-const TOP_OFFSET = 100;
-/* eslint-disable jsx-a11y/control-has-associated-label */
-
-function Headings({
-  toc,
-  isChild
-}) {
-  if (!toc.length) {
-    return null;
-  }
-
-  return <ul className={isChild ? '' : 'table-of-contents table-of-contents__left-border'}>
-      {toc.map(heading => <li key={heading.id}>
-          <a href={`#${heading.id}`} className={LINK_CLASS_NAME} // Developer provided the HTML, so assume it's safe.
-      // eslint-disable-next-line react/no-danger
-      dangerouslySetInnerHTML={{
-        __html: heading.value
-      }} />
-          <Headings isChild toc={heading.children} />
-        </li>)}
-    </ul>;
+import React from 'react';
+import clsx from 'clsx';
+import TOCItems from '@theme/TOCItems';
+import styles from './styles.module.css';
+// Using a custom className
+// This prevents TOCInline/TOCCollapsible getting highlighted by mistake
+const LINK_CLASS_NAME = 'table-of-contents__link toc-highlight';
+const LINK_ACTIVE_CLASS_NAME = 'table-of-contents__link--active';
+export default function TOC({className, ...props}) {
+  return (
+    <div className={clsx(styles.tableOfContents, 'thin-scrollbar', className)}>
+      <TOCItems
+        {...props}
+        linkClassName={LINK_CLASS_NAME}
+        linkActiveClassName={LINK_ACTIVE_CLASS_NAME}
+      />
+    </div>
+  );
 }
-
-function TOC({
-  toc
-}) {
-  (0, _useTOCHighlight.default)(LINK_CLASS_NAME, ACTIVE_LINK_CLASS_NAME, TOP_OFFSET);
-  return <div className={(0, _clsx.default)(_stylesModule.default.tableOfContents, 'thin-scrollbar')}>
-      <Headings toc={toc} />
-    </div>;
-}
-
-var _default = TOC;
-exports.default = _default;

package/lib/theme/TOC/styles.module.css

@@ -12,7 +12,7 @@
   top: calc(var(--ifm-navbar-height) + 1rem);
 }
 
-@media only screen and (max-width: 996px) {
+@media (max-width: 996px) {
   .tableOfContents {
     display: none;
   }

package/lib/theme/TOCCollapsible/CollapseButton/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/// <reference types="react" />
+import type { Props } from '@theme/TOCCollapsible/CollapseButton';
+export default function TOCCollapsibleCollapseButton({ collapsed, ...props }: Props): JSX.Element;

package/lib/theme/TOCCollapsible/CollapseButton/index.js

@@ -0,0 +1,29 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React from 'react';
+import clsx from 'clsx';
+import Translate from '@docusaurus/Translate';
+import styles from './styles.module.css';
+export default function TOCCollapsibleCollapseButton({collapsed, ...props}) {
+  return (
+    <button
+      type="button"
+      {...props}
+      className={clsx(
+        'clean-btn',
+        styles.tocCollapsibleButton,
+        !collapsed && styles.tocCollapsibleButtonExpanded,
+        props.className,
+      )}>
+      <Translate
+        id="theme.TOCCollapsible.toggleButtonLabel"
+        description="The label used by the button on the collapsible TOC component">
+        On this page
+      </Translate>
+    </button>
+  );
+}

package/lib/theme/TOCCollapsible/CollapseButton/styles.module.css

@@ -0,0 +1,29 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+.tocCollapsibleButton {
+  font-size: inherit;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 0.4rem 0.8rem;
+  width: 100%;
+}
+
+.tocCollapsibleButton::after {
+  content: '';
+  background: var(--ifm-menu-link-sublist-icon) 50% 50% / 2rem 2rem no-repeat;
+  filter: var(--ifm-menu-link-sublist-icon-filter);
+  height: 1.25rem;
+  width: 1.25rem;
+  transform: rotate(180deg);
+  transition: transform var(--ifm-transition-fast);
+}
+
+.tocCollapsibleButtonExpanded::after {
+  transform: none;
+}

package/lib/theme/TOCCollapsible/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/// <reference types="react" />
+import type { Props } from '@theme/TOCCollapsible';
+export default function TOCCollapsible({ toc, className, minHeadingLevel, maxHeadingLevel, }: Props): JSX.Element;

package/lib/theme/TOCCollapsible/index.js

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React from 'react';
+import clsx from 'clsx';
+import {useCollapsible, Collapsible} from '@docusaurus/theme-common';
+import TOCItems from '@theme/TOCItems';
+import CollapseButton from '@theme/TOCCollapsible/CollapseButton';
+import styles from './styles.module.css';
+export default function TOCCollapsible({
+  toc,
+  className,
+  minHeadingLevel,
+  maxHeadingLevel,
+}) {
+  const {collapsed, toggleCollapsed} = useCollapsible({
+    initialState: true,
+  });
+  return (
+    <div
+      className={clsx(
+        styles.tocCollapsible,
+        !collapsed && styles.tocCollapsibleExpanded,
+        className,
+      )}>
+      <CollapseButton collapsed={collapsed} onClick={toggleCollapsed} />
+      <Collapsible
+        lazy
+        className={styles.tocCollapsibleContent}
+        collapsed={collapsed}>
+        <TOCItems
+          toc={toc}
+          minHeadingLevel={minHeadingLevel}
+          maxHeadingLevel={maxHeadingLevel}
+        />
+      </Collapsible>
+    </div>
+  );
+}

package/lib/theme/TOCCollapsible/styles.module.css

@@ -0,0 +1,31 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+.tocCollapsible {
+  background-color: var(--ifm-menu-color-background-active);
+  border-radius: var(--ifm-global-radius);
+  margin: 1rem 0;
+}
+
+.tocCollapsibleContent > ul {
+  border-left: none;
+  border-top: 1px solid var(--ifm-color-emphasis-300);
+  padding: 0.2rem 0;
+  font-size: 15px;
+}
+
+.tocCollapsibleContent ul li {
+  margin: 0.4rem 0.8rem;
+}
+
+.tocCollapsibleContent a {
+  display: block;
+}
+
+.tocCollapsibleExpanded {
+  transform: none;
+}

package/lib/theme/TOCInline/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/// <reference types="react" />
+import type { Props } from '@theme/TOCInline';
+export default function TOCInline({ toc, minHeadingLevel, maxHeadingLevel, }: Props): JSX.Element;