@docusaurus/theme-classic 2.0.0-beta.fc64c12e4 → 2.0.0

package/src/theme/DocSidebarItem/Category/index.tsx

@@ -0,0 +1,211 @@
+/**
+ * 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, {type ComponentProps, useEffect, useMemo} from 'react';
+import clsx from 'clsx';
+import {
+  ThemeClassNames,
+  useThemeConfig,
+  usePrevious,
+  Collapsible,
+  useCollapsible,
+} from '@docusaurus/theme-common';
+import {
+  isActiveSidebarItem,
+  findFirstCategoryLink,
+  useDocSidebarItemsExpandedState,
+  isSamePath,
+} from '@docusaurus/theme-common/internal';
+import Link from '@docusaurus/Link';
+import {translate} from '@docusaurus/Translate';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+import DocSidebarItems from '@theme/DocSidebarItems';
+import type {Props} from '@theme/DocSidebarItem/Category';
+
+// If we navigate to a category and it becomes active, it should automatically
+// expand itself
+function useAutoExpandActiveCategory({
+  isActive,
+  collapsed,
+  updateCollapsed,
+}: {
+  isActive: boolean;
+  collapsed: boolean;
+  updateCollapsed: (b: boolean) => void;
+}) {
+  const wasActive = usePrevious(isActive);
+  useEffect(() => {
+    const justBecameActive = isActive && !wasActive;
+    if (justBecameActive && collapsed) {
+      updateCollapsed(false);
+    }
+  }, [isActive, wasActive, collapsed, updateCollapsed]);
+}
+
+/**
+ * When a collapsible category has no link, we still link it to its first child
+ * during SSR as a temporary fallback. This allows to be able to navigate inside
+ * the category even when JS fails to load, is delayed or simply disabled
+ * React hydration becomes an optional progressive enhancement
+ * see https://github.com/facebookincubator/infima/issues/36#issuecomment-772543188
+ * see https://github.com/facebook/docusaurus/issues/3030
+ */
+function useCategoryHrefWithSSRFallback(
+  item: Props['item'],
+): string | undefined {
+  const isBrowser = useIsBrowser();
+  return useMemo(() => {
+    if (item.href) {
+      return item.href;
+    }
+    // In these cases, it's not necessary to render a fallback
+    // We skip the "findFirstCategoryLink" computation
+    if (isBrowser || !item.collapsible) {
+      return undefined;
+    }
+    return findFirstCategoryLink(item);
+  }, [item, isBrowser]);
+}
+
+function CollapseButton({
+  categoryLabel,
+  onClick,
+}: {
+  categoryLabel: string;
+  onClick: ComponentProps<'button'>['onClick'];
+}) {
+  return (
+    <button
+      aria-label={translate(
+        {
+          id: 'theme.DocSidebarItem.toggleCollapsedCategoryAriaLabel',
+          message: "Toggle the collapsible sidebar category '{label}'",
+          description:
+            'The ARIA label to toggle the collapsible sidebar category',
+        },
+        {label: categoryLabel},
+      )}
+      type="button"
+      className="clean-btn menu__caret"
+      onClick={onClick}
+    />
+  );
+}
+
+export default function DocSidebarItemCategory({
+  item,
+  onItemClick,
+  activePath,
+  level,
+  index,
+  ...props
+}: Props): JSX.Element {
+  const {items, label, collapsible, className, href} = item;
+  const {
+    docs: {
+      sidebar: {autoCollapseCategories},
+    },
+  } = useThemeConfig();
+  const hrefWithSSRFallback = useCategoryHrefWithSSRFallback(item);
+
+  const isActive = isActiveSidebarItem(item, activePath);
+  const isCurrentPage = isSamePath(href, activePath);
+
+  const {collapsed, setCollapsed} = useCollapsible({
+    // Active categories are always initialized as expanded. The default
+    // (`item.collapsed`) is only used for non-active categories.
+    initialState: () => {
+      if (!collapsible) {
+        return false;
+      }
+      return isActive ? false : item.collapsed;
+    },
+  });
+
+  const {expandedItem, setExpandedItem} = useDocSidebarItemsExpandedState();
+  // Use this instead of `setCollapsed`, because it is also reactive
+  const updateCollapsed = (toCollapsed: boolean = !collapsed) => {
+    setExpandedItem(toCollapsed ? null : index);
+    setCollapsed(toCollapsed);
+  };
+  useAutoExpandActiveCategory({isActive, collapsed, updateCollapsed});
+  useEffect(() => {
+    if (
+      collapsible &&
+      expandedItem &&
+      expandedItem !== index &&
+      autoCollapseCategories
+    ) {
+      setCollapsed(true);
+    }
+  }, [collapsible, expandedItem, index, setCollapsed, autoCollapseCategories]);
+
+  return (
+    <li
+      className={clsx(
+        ThemeClassNames.docs.docSidebarItemCategory,
+        ThemeClassNames.docs.docSidebarItemCategoryLevel(level),
+        'menu__list-item',
+        {
+          'menu__list-item--collapsed': collapsed,
+        },
+        className,
+      )}>
+      <div
+        className={clsx('menu__list-item-collapsible', {
+          'menu__list-item-collapsible--active': isCurrentPage,
+        })}>
+        <Link
+          className={clsx('menu__link', {
+            'menu__link--sublist': collapsible,
+            'menu__link--sublist-caret': !href && collapsible,
+            'menu__link--active': isActive,
+          })}
+          onClick={
+            collapsible
+              ? (e) => {
+                  onItemClick?.(item);
+                  if (href) {
+                    updateCollapsed(false);
+                  } else {
+                    e.preventDefault();
+                    updateCollapsed();
+                  }
+                }
+              : () => {
+                  onItemClick?.(item);
+                }
+          }
+          aria-current={isCurrentPage ? 'page' : undefined}
+          aria-expanded={collapsible ? !collapsed : undefined}
+          href={collapsible ? hrefWithSSRFallback ?? '#' : hrefWithSSRFallback}
+          {...props}>
+          {label}
+        </Link>
+        {href && collapsible && (
+          <CollapseButton
+            categoryLabel={label}
+            onClick={(e) => {
+              e.preventDefault();
+              updateCollapsed();
+            }}
+          />
+        )}
+      </div>
+
+      <Collapsible lazy as="ul" className="menu__list" collapsed={collapsed}>
+        <DocSidebarItems
+          items={items}
+          tabIndex={collapsed ? -1 : 0}
+          onItemClick={onItemClick}
+          activePath={activePath}
+          level={level + 1}
+        />
+      </Collapsible>
+    </li>
+  );
+}

package/src/theme/DocSidebarItem/Html/index.tsx

@@ -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 clsx from 'clsx';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import type {Props} from '@theme/DocSidebarItem/Html';
+
+import styles from './styles.module.css';
+
+export default function DocSidebarItemHtml({
+  item,
+  level,
+  index,
+}: Props): JSX.Element {
+  const {value, defaultStyle, className} = item;
+  return (
+    <li
+      className={clsx(
+        ThemeClassNames.docs.docSidebarItemLink,
+        ThemeClassNames.docs.docSidebarItemLinkLevel(level),
+        defaultStyle && [styles.menuHtmlItem, 'menu__list-item'],
+        className,
+      )}
+      key={index}
+      // eslint-disable-next-line react/no-danger
+      dangerouslySetInnerHTML={{__html: value}}
+    />
+  );
+}

package/{lib/theme/DocSidebarItem → src/theme/DocSidebarItem/Html}/styles.module.css

@@ -6,10 +6,8 @@
  */
 
 @media (min-width: 997px) {
-  .menuLinkText {
-    cursor: initial;
-  }
-  .menuLinkText:hover {
-    background: none;
+  .menuHtmlItem {
+    padding: var(--ifm-menu-link-padding-vertical)
+      var(--ifm-menu-link-padding-horizontal);
   }
 }

package/src/theme/DocSidebarItem/Link/index.tsx

@@ -0,0 +1,58 @@
+/**
+ * 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 {ThemeClassNames} from '@docusaurus/theme-common';
+import {isActiveSidebarItem} from '@docusaurus/theme-common/internal';
+import Link from '@docusaurus/Link';
+import isInternalUrl from '@docusaurus/isInternalUrl';
+import IconExternalLink from '@theme/Icon/ExternalLink';
+import type {Props} from '@theme/DocSidebarItem/Link';
+
+import styles from './styles.module.css';
+
+export default function DocSidebarItemLink({
+  item,
+  onItemClick,
+  activePath,
+  level,
+  index,
+  ...props
+}: Props): JSX.Element {
+  const {href, label, className} = item;
+  const isActive = isActiveSidebarItem(item, activePath);
+  const isInternalLink = isInternalUrl(href);
+  return (
+    <li
+      className={clsx(
+        ThemeClassNames.docs.docSidebarItemLink,
+        ThemeClassNames.docs.docSidebarItemLinkLevel(level),
+        'menu__list-item',
+        className,
+      )}
+      key={label}>
+      <Link
+        className={clsx(
+          'menu__link',
+          !isInternalLink && styles.menuExternalLink,
+          {
+            'menu__link--active': isActive,
+          },
+        )}
+        aria-current={isActive ? 'page' : undefined}
+        to={href}
+        {...(isInternalLink && {
+          onClick: onItemClick ? () => onItemClick(item) : undefined,
+        })}
+        {...props}>
+        {label}
+        {!isInternalLink && <IconExternalLink />}
+      </Link>
+    </li>
+  );
+}

package/src/theme/DocSidebarItem/Link/styles.module.css

@@ -0,0 +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.
+ */
+
+.menuExternalLink {
+  align-items: center;
+}

package/src/theme/DocSidebarItem/index.tsx

@@ -5,57 +5,11 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {useEffect, memo} from 'react';
-import clsx from 'clsx';
-import {
-  isSamePath,
-  usePrevious,
-  Collapsible,
-  useCollapsible,
-} from '@docusaurus/theme-common';
-import Link from '@docusaurus/Link';
-import isInternalUrl from '@docusaurus/isInternalUrl';
-import IconExternalLink from '@theme/IconExternalLink';
-
-import type {Props, DocSidebarItemsProps} from '@theme/DocSidebarItem';
-import type {
-  PropSidebarItemCategory,
-  PropSidebarItemLink,
-} from '@docusaurus/plugin-content-docs-types';
-
-import styles from './styles.module.css';
-
-const isActiveSidebarItem = (item: Props['item'], activePath: string) => {
-  if (item.type === 'link') {
-    return isSamePath(item.href, activePath);
-  }
-  if (item.type === 'category') {
-    return item.items.some((subItem) =>
-      isActiveSidebarItem(subItem, activePath),
-    );
-  }
-  return false;
-};
-
-// Optimize sidebar at each "level"
-// TODO this item should probably not receive the "activePath" props
-// TODO this triggers whole sidebar re-renders on navigation
-export const DocSidebarItems = memo(function DocSidebarItems({
-  items,
-  ...props
-}: DocSidebarItemsProps): JSX.Element {
-  return (
-    <>
-      {items.map((item, index) => (
-        <DocSidebarItem
-          key={index} // sidebar is static, the index does not change
-          item={item}
-          {...props}
-        />
-      ))}
-    </>
-  );
-});
+import React from 'react';
+import DocSidebarItemCategory from '@theme/DocSidebarItem/Category';
+import DocSidebarItemLink from '@theme/DocSidebarItem/Link';
+import DocSidebarItemHtml from '@theme/DocSidebarItem/Html';
+import type {Props} from '@theme/DocSidebarItem';
 
 export default function DocSidebarItem({
   item,
@@ -63,125 +17,11 @@ export default function DocSidebarItem({
 }: Props): JSX.Element | null {
   switch (item.type) {
     case 'category':
-      if (item.items.length === 0) {
-        return null;
-      }
       return <DocSidebarItemCategory item={item} {...props} />;
+    case 'html':
+      return <DocSidebarItemHtml item={item} {...props} />;
     case 'link':
     default:
       return <DocSidebarItemLink item={item} {...props} />;
   }
 }
-
-// If we navigate to a category and it becomes active, it should automatically expand itself
-function useAutoExpandActiveCategory({
-  isActive,
-  collapsed,
-  setCollapsed,
-}: {
-  isActive: boolean;
-  collapsed: boolean;
-  setCollapsed: (b: boolean) => void;
-}) {
-  const wasActive = usePrevious(isActive);
-  useEffect(() => {
-    const justBecameActive = isActive && !wasActive;
-    if (justBecameActive && collapsed) {
-      setCollapsed(false);
-    }
-  }, [isActive, wasActive, collapsed]);
-}
-
-function DocSidebarItemCategory({
-  item,
-  onItemClick,
-  activePath,
-  ...props
-}: Props & {item: PropSidebarItemCategory}) {
-  const {items, label, collapsible} = item;
-
-  const isActive = isActiveSidebarItem(item, activePath);
-
-  const {collapsed, setCollapsed, toggleCollapsed} = useCollapsible({
-    // active categories are always initialized as expanded
-    // the default (item.collapsed) is only used for non-active categories
-    initialState: () => {
-      if (!collapsible) {
-        return false;
-      }
-      return isActive ? false : item.collapsed;
-    },
-  });
-
-  useAutoExpandActiveCategory({isActive, collapsed, setCollapsed});
-
-  return (
-    <li
-      className={clsx('menu__list-item', {
-        'menu__list-item--collapsed': collapsed,
-      })}>
-      {/* eslint-disable-next-line jsx-a11y/anchor-is-valid */}
-      <a
-        className={clsx('menu__link', {
-          'menu__link--sublist': collapsible,
-          'menu__link--active': collapsible && isActive,
-          [styles.menuLinkText]: !collapsible,
-        })}
-        onClick={
-          collapsible
-            ? (e) => {
-                e.preventDefault();
-                toggleCollapsed();
-              }
-            : undefined
-        }
-        href={collapsible ? '#' : undefined}
-        {...props}>
-        {label}
-      </a>
-
-      <Collapsible lazy as="ul" className="menu__list" collapsed={collapsed}>
-        <DocSidebarItems
-          items={items}
-          tabIndex={collapsed ? -1 : 0}
-          onItemClick={onItemClick}
-          activePath={activePath}
-        />
-      </Collapsible>
-    </li>
-  );
-}
-
-function DocSidebarItemLink({
-  item,
-  onItemClick,
-  activePath,
-  ...props
-}: Props & {item: PropSidebarItemLink}) {
-  const {href, label} = item;
-  const isActive = isActiveSidebarItem(item, activePath);
-  return (
-    <li className="menu__list-item" key={label}>
-      <Link
-        className={clsx('menu__link', {
-          'menu__link--active': isActive,
-        })}
-        to={href}
-        {...(isInternalUrl(href) && {
-          isNavLink: true,
-          exact: true,
-          onClick: onItemClick,
-        })}
-        {...props}>
-        {isInternalUrl(href) ? (
-          label
-        ) : (
-          <span>
-            {label}
-            <IconExternalLink />
-          </span>
-        )}
-      </Link>
-    </li>
-  );
-}

package/src/theme/DocSidebarItems/index.tsx

@@ -0,0 +1,27 @@
+/**
+ * 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, {memo} from 'react';
+import {DocSidebarItemsExpandedStateProvider} from '@docusaurus/theme-common/internal';
+import DocSidebarItem from '@theme/DocSidebarItem';
+
+import type {Props} from '@theme/DocSidebarItems';
+
+// TODO this item should probably not receive the "activePath" props
+// TODO this triggers whole sidebar re-renders on navigation
+function DocSidebarItems({items, ...props}: Props): JSX.Element {
+  return (
+    <DocSidebarItemsExpandedStateProvider>
+      {items.map((item, index) => (
+        <DocSidebarItem key={index} item={item} index={index} {...props} />
+      ))}
+    </DocSidebarItemsExpandedStateProvider>
+  );
+}
+
+// Optimize sidebar at each "level"
+export default memo(DocSidebarItems);

package/src/theme/DocTagDocListPage/index.tsx

@@ -0,0 +1,95 @@
+/**
+ * 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';
+import {
+  PageMetadata,
+  HtmlClassNameProvider,
+  ThemeClassNames,
+  usePluralForm,
+} from '@docusaurus/theme-common';
+import Translate, {translate} from '@docusaurus/Translate';
+import Layout from '@theme/Layout';
+import SearchMetadata from '@theme/SearchMetadata';
+import type {Props} from '@theme/DocTagDocListPage';
+
+// Very simple pluralization: probably good enough for now
+function useNDocsTaggedPlural() {
+  const {selectMessage} = usePluralForm();
+  return (count: number) =>
+    selectMessage(
+      count,
+      translate(
+        {
+          id: 'theme.docs.tagDocListPageTitle.nDocsTagged',
+          description:
+            'Pluralized label for "{count} docs tagged". Use as much plural forms (separated by "|") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)',
+          message: 'One doc tagged|{count} docs tagged',
+        },
+        {count},
+      ),
+    );
+}
+
+function DocItem({doc}: {doc: Props['tag']['items'][number]}): JSX.Element {
+  return (
+    <article className="margin-vert--lg">
+      <Link to={doc.permalink}>
+        <h2>{doc.title}</h2>
+      </Link>
+      {doc.description && <p>{doc.description}</p>}
+    </article>
+  );
+}
+
+export default function DocTagDocListPage({tag}: Props): JSX.Element {
+  const nDocsTaggedPlural = useNDocsTaggedPlural();
+  const title = translate(
+    {
+      id: 'theme.docs.tagDocListPageTitle',
+      description: 'The title of the page for a docs tag',
+      message: '{nDocsTagged} with "{tagName}"',
+    },
+    {nDocsTagged: nDocsTaggedPlural(tag.count), tagName: tag.label},
+  );
+
+  return (
+    <HtmlClassNameProvider
+      className={clsx(
+        ThemeClassNames.wrapper.docsPages,
+        ThemeClassNames.page.docsTagDocListPage,
+      )}>
+      <PageMetadata title={title} />
+      <SearchMetadata tag="doc_tag_doc_list" />
+      <Layout>
+        <div className="container margin-vert--lg">
+          <div className="row">
+            <main className="col col--8 col--offset-2">
+              <header className="margin-bottom--xl">
+                <h1>{title}</h1>
+                <Link href={tag.allTagsPath}>
+                  <Translate
+                    id="theme.tags.tagsPageLink"
+                    description="The label of the link targeting the tag list page">
+                    View All Tags
+                  </Translate>
+                </Link>
+              </header>
+              <section className="margin-vert--lg">
+                {tag.items.map((doc) => (
+                  <DocItem key={doc.id} doc={doc} />
+                ))}
+              </section>
+            </main>
+          </div>
+        </div>
+      </Layout>
+    </HtmlClassNameProvider>
+  );
+}

package/src/theme/DocTagsListPage/index.tsx

@@ -0,0 +1,43 @@
+/**
+ * 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 {
+  PageMetadata,
+  HtmlClassNameProvider,
+  ThemeClassNames,
+  translateTagsPageTitle,
+} from '@docusaurus/theme-common';
+import Layout from '@theme/Layout';
+import TagsListByLetter from '@theme/TagsListByLetter';
+import SearchMetadata from '@theme/SearchMetadata';
+import type {Props} from '@theme/DocTagsListPage';
+
+export default function DocTagsListPage({tags}: Props): JSX.Element {
+  const title = translateTagsPageTitle();
+  return (
+    <HtmlClassNameProvider
+      className={clsx(
+        ThemeClassNames.wrapper.docsPages,
+        ThemeClassNames.page.docsTagsListPage,
+      )}>
+      <PageMetadata title={title} />
+      <SearchMetadata tag="doc_tags_list" />
+      <Layout>
+        <div className="container margin-vert--lg">
+          <div className="row">
+            <main className="col col--8 col--offset-2">
+              <h1>{title}</h1>
+              <TagsListByLetter tags={tags} />
+            </main>
+          </div>
+        </div>
+      </Layout>
+    </HtmlClassNameProvider>
+  );
+}