@seqera/docusaurus-theme-seqera 1.0.0

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

@@ -0,0 +1,309 @@
+
+
+import React, {
+  type ComponentProps,
+  type ReactNode,
+  useEffect,
+  useMemo,
+} from 'react';
+import clsx from 'clsx';
+import {
+  ThemeClassNames,
+  useThemeConfig,
+  usePrevious,
+  Collapsible,
+  useCollapsible,
+} from '@docusaurus/theme-common';
+import {isSamePath} from '@docusaurus/theme-common/internal';
+import {
+  isActiveSidebarItem,
+  findFirstSidebarItemLink,
+  useDocSidebarItemsExpandedState,
+  useVisibleSidebarItems,
+} from '@docusaurus/plugin-content-docs/client';
+import Link from '@docusaurus/Link';
+import {translate} from '@docusaurus/Translate';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+import DocSidebarItems from '@theme/DocSidebarItems';
+import DocSidebarItemLink from '@theme/DocSidebarItem/Link';
+import type {Props} from '@theme/DocSidebarItem/Category';
+
+import type {
+  PropSidebarItemCategory,
+  PropSidebarItemLink,
+} from '@docusaurus/plugin-content-docs';
+import styles from './styles.module.css';
+
+// If we navigate to a category and it becomes active, it should automatically
+// expand itself
+function useAutoExpandActiveCategory({
+  isActive,
+  collapsed,
+  updateCollapsed,
+  activePath,
+}: {
+  isActive: boolean;
+  collapsed: boolean;
+  updateCollapsed: (b: boolean) => void;
+  activePath: string;
+}) {
+  const wasActive = usePrevious(isActive);
+  const previousActivePath = usePrevious(activePath);
+  useEffect(() => {
+    const justBecameActive = isActive && !wasActive;
+    const stillActiveButPathChanged =
+      isActive && wasActive && activePath !== previousActivePath;
+    if ((justBecameActive || stillActiveButPathChanged) && collapsed) {
+      updateCollapsed(false);
+    }
+  }, [
+    isActive,
+    wasActive,
+    collapsed,
+    updateCollapsed,
+    activePath,
+    previousActivePath,
+  ]);
+}
+
+/**
+ * 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 && !item.linkUnlisted) {
+      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 findFirstSidebarItemLink(item);
+  }, [item, isBrowser]);
+}
+
+function CollapseButton({
+  collapsed,
+  categoryLabel,
+  onClick,
+}: {
+  collapsed: boolean;
+  categoryLabel: string;
+  onClick: ComponentProps<'button'>['onClick'];
+}) {
+  return (
+    <button
+      aria-label={
+        collapsed
+          ? translate(
+              {
+                id: 'theme.DocSidebarItem.expandCategoryAriaLabel',
+                message: "Expand sidebar category '{label}'",
+                description: 'The ARIA label to expand the sidebar category',
+              },
+              {label: categoryLabel},
+            )
+          : translate(
+              {
+                id: 'theme.DocSidebarItem.collapseCategoryAriaLabel',
+                message: "Collapse sidebar category '{label}'",
+                description: 'The ARIA label to collapse the sidebar category',
+              },
+              {label: categoryLabel},
+            )
+      }
+      aria-expanded={!collapsed}
+      type="button"
+      className="clean-btn menu__caret"
+      onClick={onClick}
+    />
+  );
+}
+
+function CategoryLinkLabel({label}: {label: string}) {
+  return (
+    <div title={label} className={`${styles.categoryLinkLabel}`}>
+      {label}
+    </div>
+  );
+}
+
+export default function DocSidebarItemCategory(props: Props): ReactNode {
+  const visibleChildren = useVisibleSidebarItems(
+    props.item.items,
+    props.activePath,
+  );
+  if (visibleChildren.length === 0) {
+    return <DocSidebarItemCategoryEmpty {...props} />;
+  } else {
+    return <DocSidebarItemCategoryCollapsible {...props} />;
+  }
+}
+
+function isCategoryWithHref(
+  category: PropSidebarItemCategory,
+): category is PropSidebarItemCategory & {href: string} {
+  return typeof category.href === 'string';
+}
+
+// If a category doesn't have any visible children, we render it as a link
+function DocSidebarItemCategoryEmpty({item, ...props}: Props): ReactNode {
+  // If the category has no link, we don't render anything
+  // It's not super useful to render a category you can't open nor click
+  if (!isCategoryWithHref(item)) {
+    return null;
+  }
+  // We remove props that don't make sense for a link and forward the rest
+  const {
+    type,
+    collapsed,
+    collapsible,
+    items,
+    linkUnlisted,
+    ...forwardableProps
+  } = item;
+  const linkItem: PropSidebarItemLink = {
+    type: 'link',
+    ...forwardableProps,
+  };
+  return <DocSidebarItemLink item={linkItem} {...props} />;
+}
+
+function DocSidebarItemCategoryCollapsible({
+  item,
+  onItemClick,
+  activePath,
+  level,
+  index,
+  ...props
+}: Props): ReactNode {
+  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,
+    activePath,
+  });
+  useEffect(() => {
+    if (
+      collapsible &&
+      expandedItem != null &&
+      expandedItem !== index &&
+      autoCollapseCategories
+    ) {
+      setCollapsed(true);
+    }
+  }, [collapsible, expandedItem, index, setCollapsed, autoCollapseCategories]);
+
+  const handleItemClick: ComponentProps<'a'>['onClick'] = (e) => {
+    onItemClick?.(item);
+    if (collapsible) {
+      if (href) {
+        // When already on the category's page, we collapse it
+        // We don't use "isActive" because it would collapse the
+        // category even when we browse a children element
+        // See https://github.com/facebook/docusaurus/issues/11213
+        if (isCurrentPage) {
+          e.preventDefault();
+          updateCollapsed();
+        } else {
+          // When navigating to a new category, we always expand
+          // see https://github.com/facebook/docusaurus/issues/10854#issuecomment-2609616182
+          updateCollapsed(false);
+        }
+      } else {
+        e.preventDefault();
+        updateCollapsed();
+      }
+    }
+  };
+
+  return (
+    <li
+      className={clsx(
+        ThemeClassNames.docs.docSidebarItemCategory,
+        ThemeClassNames.docs.docSidebarItemCategoryLevel(level),
+        'menu__list-item',
+        {
+          'menu__list-item--collapsed': collapsed,
+        },
+        className,
+      )}>
+      <div
+        className={clsx('w-full flex flex-row bg-transparent hover:bg-transparent focus:bg-transparent active:bg-transparent hover:text-primary menu__list-item-collapsible', {
+          'menu__list-item-collapsible--active': isCurrentPage,
+        })}>
+        <Link
+          className={clsx(styles.categoryLink, 'menu__link w-full hover:bg-transparent hover:text-primary', {
+            'menu__link--sublist ': collapsible,
+            'menu__link--sublist-caret': !href && collapsible,
+            'menu__link--active': isActive,
+          })}
+          onClick={handleItemClick}
+          aria-current={isCurrentPage ? 'page' : undefined}
+          role={collapsible && !href ? 'button' : undefined}
+          aria-expanded={collapsible && !href ? !collapsed : undefined}
+          href={collapsible ? hrefWithSSRFallback ?? '#' : hrefWithSSRFallback}
+          {...props}>
+          <CategoryLinkLabel label={label} />
+        </Link>
+        {href && collapsible && (
+          <CollapseButton
+            collapsed={collapsed}
+            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/Category/styles.module.css

@@ -0,0 +1,35 @@
+
+
+.categoryLink {
+  overflow: hidden;
+}
+
+:global(.menu__link--sublist-caret)::after {
+  margin-left: var(--ifm-menu-link-padding-vertical);
+  background-image: url("data:image/svg+xml,%3Csvg width='25' height='24' viewBox='0 0 25 24' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M12.4943 10.4038L7.7174 15.1615L7.16162 14.6057L12.4943 9.29225L17.8078 14.6057L17.252 15.1615L12.4943 10.4038Z' fill='%23160F26'/%3E%3C/svg%3E%0A");
+  background-repeat: no-repeat;
+  background-size: 120%;
+  transform: rotateZ(180deg);
+}
+:global(.menu__link--sublist-caret[aria-expanded="true"])::after {
+    transform: rotateZ(0deg);
+}
+:global(.menu__caret)::before {
+  background-image: url("data:image/svg+xml,%3Csvg width='25' height='24' viewBox='0 0 25 24' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M12.4943 10.4038L7.7174 15.1615L7.16162 14.6057L12.4943 9.29225L17.8078 14.6057L17.252 15.1615L12.4943 10.4038Z' fill='%23160F26'/%3E%3C/svg%3E%0A");
+  background-repeat: no-repeat;
+  background-size: 120%;
+  transform: rotateZ(180deg);
+  margin-left: -1rem;
+}
+:global(.menu__caret[aria-expanded="true"]):before {
+    transform: rotateZ(0deg);
+}
+
+.categoryLinkLabel {
+  flex: 1;
+  overflow: hidden;
+  display: -webkit-box;
+  line-clamp: 2;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+}

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

@@ -0,0 +1,30 @@
+import React, {type ReactNode} 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): ReactNode {
+  const {value, defaultStyle, className} = item;
+  return (
+    <li
+      className={clsx(
+        ThemeClassNames.docs.docSidebarItemLink,
+        ThemeClassNames.docs.docSidebarItemLinkLevel(level),
+        level > 1 &&
+          ThemeClassNames.docs.docSidebarItemLinkLevel(level) &&
+          'ml-2',
+        defaultStyle && [styles.menuHtmlItem, 'menu__list-item '],
+        className,
+      )}
+      key={index}
+      // eslint-disable-next-line react/no-danger
+      dangerouslySetInnerHTML={{__html: value}}
+    />
+  );
+}

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

@@ -0,0 +1,8 @@
+
+
+@media (min-width: 997px) {
+  .menuHtmlItem {
+    padding: var(--ifm-menu-link-padding-vertical)
+      var(--ifm-menu-link-padding-horizontal);
+  }
+}

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

@@ -0,0 +1,62 @@
+import React, {type ReactNode} from 'react';
+import clsx from 'clsx';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import {isActiveSidebarItem} from '@docusaurus/plugin-content-docs/client';
+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';
+
+function LinkLabel({label}: {label: string}) {
+  return (
+    <span title={label} className={styles.linkLabel}>
+      {label}
+    </span>
+  );
+}
+
+export default function DocSidebarItemLink({
+  item,
+  onItemClick,
+  activePath,
+  level,
+  index,
+  ...props
+}: Props): ReactNode {
+  const {href, label, className, autoAddBaseUrl} = item;
+  const isActive = isActiveSidebarItem(item, activePath);
+  const isInternalLink = isInternalUrl(href);
+  return (
+    <li
+      className={clsx(
+        ThemeClassNames.docs.docSidebarItemLink,
+        ThemeClassNames.docs.docSidebarItemLinkLevel(level),
+         level > 1 && ThemeClassNames.docs.docSidebarItemLinkLevel(level) && 'ml-2',
+        'menu__list-item',
+        className,
+      )}
+      key={label}>
+      <Link
+        className={clsx(
+          'menu__link hover:bg-transparent hover:text-primary',
+          !isInternalLink && styles.menuExternalLink,
+          {
+            'text-primary hover:bg-transparent focus:bg-transparent active:bg-transparent':
+              isActive,
+          },
+        )}
+        autoAddBaseUrl={autoAddBaseUrl}
+        aria-current={isActive ? 'page' : undefined}
+        to={href}
+        {...(isInternalLink && {
+          onClick: onItemClick ? () => onItemClick(item) : undefined,
+        })}
+        {...props}>
+        <LinkLabel label={label} />
+        {!isInternalLink && <IconExternalLink />}
+      </Link>
+    </li>
+  );
+}

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

@@ -0,0 +1,13 @@
+
+
+.menuExternalLink {
+  align-items: center;
+}
+
+.linkLabel {
+  overflow: hidden;
+  display: -webkit-box;
+  line-clamp: 2;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+}

package/src/theme/DocSidebarItem/index.tsx

@@ -0,0 +1,19 @@
+
+
+import React, {type ReactNode} 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, ...props}: Props): ReactNode {
+  switch (item.type) {
+    case 'category':
+      return <div className="mt-3 md:mt-0"><DocSidebarItemCategory item={item} {...props} /></div>;
+    case 'html':
+      return <div className="mt-3 md:mt-0"><DocSidebarItemHtml item={item} {...props} /></div>;
+    case 'link':
+    default:
+      return <div className="mt-3 md:mt-0"><DocSidebarItemLink item={item} {...props} /></div>;
+  }
+}

package/src/theme/DocSidebarItems/index.tsx

@@ -0,0 +1,24 @@
+
+
+import React, {memo, type ReactNode} from 'react';
+import {
+  DocSidebarItemsExpandedStateProvider,
+  useVisibleSidebarItems,
+} from '@docusaurus/plugin-content-docs/client';
+import DocSidebarItem from '@theme/DocSidebarItem';
+
+import type {Props} from '@theme/DocSidebarItems';
+
+function DocSidebarItems({items, ...props}: Props): ReactNode {
+  const visibleItems = useVisibleSidebarItems(items, props.activePath);
+  return (
+    <DocSidebarItemsExpandedStateProvider>
+      {visibleItems.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,113 @@
+
+
+import React, {type ReactNode} 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 SearchMetadata from '@theme/SearchMetadata';
+import type {Props} from '@theme/DocTagDocListPage';
+import Unlisted from '@theme/ContentVisibility/Unlisted';
+import Heading from '@theme/Heading';
+
+// 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 usePageTitle(props: Props): string {
+  const nDocsTaggedPlural = useNDocsTaggedPlural();
+  return translate(
+    {
+      id: 'theme.docs.tagDocListPageTitle',
+      description: 'The title of the page for a docs tag',
+      message: '{nDocsTagged} with "{tagName}"',
+    },
+    {nDocsTagged: nDocsTaggedPlural(props.tag.count), tagName: props.tag.label},
+  );
+}
+
+function DocItem({doc}: {doc: Props['tag']['items'][number]}): ReactNode {
+  return (
+    <article className="margin-vert--lg">
+      <Link to={doc.permalink}>
+        <Heading as="h2">{doc.title}</Heading>
+      </Link>
+      {doc.description && <p>{doc.description}</p>}
+    </article>
+  );
+}
+
+function DocTagDocListPageMetadata({
+  title,
+  tag,
+}: Props & {title: string}): ReactNode {
+  return (
+    <>
+      <PageMetadata title={title} description={tag.description} />
+      <SearchMetadata tag="doc_tag_doc_list" />
+    </>
+  );
+}
+
+function DocTagDocListPageContent({
+  tag,
+  title,
+}: Props & {title: string}): ReactNode {
+  return (
+    <HtmlClassNameProvider
+      className={clsx(ThemeClassNames.page.docsTagDocListPage)}>
+      <div className="container margin-vert--lg">
+        <div className="row">
+          <main className="col col--8 col--offset-2">
+            {tag.unlisted && <Unlisted />}
+            <header className="margin-bottom--xl">
+              <Heading as="h1">{title}</Heading>
+              {tag.description && <p>{tag.description}</p>}
+              <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>
+    </HtmlClassNameProvider>
+  );
+}
+
+export default function DocTagDocListPage(props: Props): ReactNode {
+  const title = usePageTitle(props);
+  return (
+    <>
+      <DocTagDocListPageMetadata {...props} title={title} />
+      <DocTagDocListPageContent {...props} title={title} />
+    </>
+  );
+}

package/src/theme/DocTagsListPage/index.tsx

@@ -0,0 +1,52 @@
+
+
+import React, {type ReactNode} from 'react';
+import clsx from 'clsx';
+import {
+  PageMetadata,
+  HtmlClassNameProvider,
+  ThemeClassNames,
+  translateTagsPageTitle,
+} from '@docusaurus/theme-common';
+import TagsListByLetter from '@theme/TagsListByLetter';
+import SearchMetadata from '@theme/SearchMetadata';
+import type {Props} from '@theme/DocTagsListPage';
+import Heading from '@theme/Heading';
+
+function DocTagsListPageMetadata({title}: Props & {title: string}): ReactNode {
+  return (
+    <>
+      <PageMetadata title={title} />
+      <SearchMetadata tag="doc_tags_list" />
+    </>
+  );
+}
+
+function DocTagsListPageContent({
+  tags,
+  title,
+}: Props & {title: string}): ReactNode {
+  return (
+    <HtmlClassNameProvider
+      className={clsx(ThemeClassNames.page.docsTagsListPage)}>
+      <div className="container margin-vert--lg">
+        <div className="row">
+          <main className="col col--8 col--offset-2">
+            <Heading as="h1">{title}</Heading>
+            <TagsListByLetter tags={tags} />
+          </main>
+        </div>
+      </div>
+    </HtmlClassNameProvider>
+  );
+}
+
+export default function DocTagsListPage(props: Props): ReactNode {
+  const title = translateTagsPageTitle();
+  return (
+    <>
+      <DocTagsListPageMetadata {...props} title={title} />
+      <DocTagsListPageContent {...props} title={title} />
+    </>
+  );
+}