@azerion/bunosaurus-theme-common 0.0.0-stage → 4.0.0

package/src/index.ts

@@ -0,0 +1,112 @@
+/**
+ * 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.
+ */
+
+/*
+ * APIs to document
+ */
+
+export {
+  useThemeConfig,
+  type ThemeConfig,
+  type UserThemeConfig,
+  type Navbar,
+  type NavbarItem,
+  type NavbarLogo,
+  type MultiColumnFooter,
+  type SimpleFooter,
+  type Footer,
+  type FooterColumnItem,
+  type FooterLogo,
+  type FooterLinkItem,
+  type ColorModeConfig,
+} from './utils/useThemeConfig';
+
+export {default as ThemedComponent} from './components/ThemedComponent';
+
+export {
+  createStorageSlot,
+  useStorageSlot,
+  listStorageKeys,
+} from './utils/storageUtils';
+
+export {usePluralForm} from './utils/usePluralForm';
+
+export {useCollapsible, Collapsible} from './components/Collapsible';
+
+export {ThemeClassNames} from './utils/ThemeClassNames';
+
+export {prefersReducedMotion} from './utils/accessibilityUtils';
+
+export {
+  useEvent,
+  usePrevious,
+  composeProviders,
+  ReactContextError,
+} from './utils/reactUtils';
+
+export {PageMetadata, HtmlClassNameProvider} from './utils/metadataUtils';
+
+export {useColorMode, type ColorMode} from './contexts/colorMode';
+
+export {
+  NavbarSecondaryMenuFiller,
+  type NavbarSecondaryMenuComponent,
+} from './contexts/navbarSecondaryMenu/content';
+
+export {useWindowSize} from './hooks/useWindowSize';
+
+/*
+ * APIs kept undocumented, on purpose
+ * Note: we still guarantee retro-compatibility on those
+ */
+
+export {
+  translateTagsPageTitle,
+  TagsPageLinkLabel,
+  listTagsByLetters,
+  type TagLetterEntry,
+} from './utils/tagsUtils';
+
+export {useAnchorTargetClassName} from './utils/anchorUtils';
+
+export {isMultiColumnFooterLinks} from './utils/footerUtils';
+
+export {isRegexpStringMatch} from './utils/regexpUtils';
+
+export {duplicates, uniq, groupBy} from './utils/jsUtils';
+
+export {usePrismTheme} from './hooks/usePrismTheme';
+
+export {processAdmonitionProps} from './utils/admonitionUtils';
+
+export {
+  useHistorySelector,
+  useQueryString,
+  useQueryStringList,
+  useClearQueryString,
+  mergeSearchParams,
+  mergeSearchStrings,
+} from './utils/historyUtils';
+
+export {
+  SkipToContentFallbackId,
+  SkipToContentLink,
+} from './utils/skipToContentUtils';
+
+export {
+  UnlistedBannerTitle,
+  UnlistedBannerMessage,
+  DraftBannerTitle,
+  DraftBannerMessage,
+} from './translations/contentVisibilityTranslations';
+
+export {
+  ErrorBoundaryTryAgainButton,
+  ErrorBoundaryError,
+  ErrorBoundaryErrorMessageFallback,
+  ErrorCauseBoundary,
+} from './utils/errorBoundaryUtils';

package/src/internal.ts

@@ -0,0 +1,107 @@
+/**
+ * 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.
+ */
+
+// This re-export permits to handle some level of retro-compatibility. Users
+// might swizzle unsafe components and expose these internal imports. When we
+// move an API from internal to public, former internal imports should keep
+// working, so that the change doesn't become breaking.
+//
+// Important: this line is removed from build output with the
+// "removeThemeInternalReexport" script for CI checks. This ensures that none of
+// our internal code relies on this re-export and that we don't forget to
+// migrate theme internal imports to public imports.
+//
+// eslint-disable-next-line no-restricted-syntax
+export * from './index';
+
+export {
+  AnnouncementBarProvider,
+  useAnnouncementBar,
+} from './contexts/announcementBar';
+
+export {
+  sanitizeTabsChildren,
+  TabsProvider,
+  useTabs,
+  useTabsContextValue,
+} from './utils/tabsUtils';
+export type {TabValue, TabsProps, TabItemProps} from './utils/tabsUtils';
+
+export {useNavbarMobileSidebar} from './contexts/navbarMobileSidebar';
+export {useNavbarSecondaryMenu} from './contexts/navbarSecondaryMenu/display';
+
+export {ColorModeProvider} from './contexts/colorMode';
+
+export {useAlternatePageUtils} from './utils/useAlternatePageUtils';
+
+export {
+  type CodeBlockMetadata,
+  createCodeBlockMetadata,
+  getPrismCssVariables,
+  CodeBlockContextProvider,
+  useCodeBlockContext,
+} from './utils/codeBlockUtils';
+
+export {DEFAULT_SEARCH_TAG} from './utils/searchUtils';
+
+export {
+  TitleFormatterProvider,
+  useTitleFormatter,
+} from './utils/titleFormatterUtils';
+
+export {useLocationChange} from './utils/useLocationChange';
+
+export {useLocalPathname} from './utils/useLocalPathname';
+
+export {
+  useHistoryPopHandler,
+  useHistorySelector,
+  useQueryStringValue,
+} from './utils/historyUtils';
+
+export {
+  useFilteredAndTreeifiedTOC,
+  useTreeifiedTOC,
+  type TOCTreeNode,
+} from './utils/tocUtils';
+
+export {
+  ScrollControllerProvider,
+  useScrollController,
+  useScrollPosition,
+  useScrollPositionBlocker,
+  useSmoothScrollTo,
+} from './utils/scrollUtils';
+
+export {useHomePageRoute, isSamePath} from './utils/routesUtils';
+
+export {PluginHtmlClassNameProvider} from './utils/metadataUtils';
+
+export {splitNavbarItems, NavbarProvider} from './utils/navbarUtils';
+
+export {extractLeadingEmoji} from './utils/emojiUtils';
+
+export {
+  useTOCHighlight,
+  type TOCHighlightConfig,
+} from './hooks/useTOCHighlight';
+
+export {useDateTimeFormat} from './utils/IntlUtils';
+
+export {useHideableNavbar} from './hooks/useHideableNavbar';
+export {useLockBodyScroll} from './hooks/useLockBodyScroll';
+export {useCodeWordWrap} from './hooks/useCodeWordWrap';
+export {useBackToTopButton} from './hooks/useBackToTopButton';
+
+export {useDocCardDescriptionCategoryItemsPlural} from './translations/docsTranslations';
+export {
+  useBlogTagsPostsPageTitle,
+  useBlogAuthorPageTitle,
+  translateBlogAuthorsListPageTitle,
+  BlogAuthorsListViewAllLabel,
+  BlogAuthorNoPostsLabel,
+} from './translations/blogTranslations';

package/src/translations/blogTranslations.tsx

@@ -0,0 +1,89 @@
+/**
+ * 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 type {ReactNode} from 'react';
+import Translate, {translate} from '@docusaurus/Translate';
+import {usePluralForm} from '../utils/usePluralForm';
+
+// Only used locally
+function useBlogPostsPlural(): (count: number) => string {
+  const {selectMessage} = usePluralForm();
+  return (count: number) =>
+    selectMessage(
+      count,
+      translate(
+        {
+          id: 'theme.blog.post.plurals',
+          description:
+            'Pluralized label for "{count} posts". 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 post|{count} posts',
+        },
+        {count},
+      ),
+    );
+}
+
+export function useBlogTagsPostsPageTitle(tag: {
+  label: string;
+  count: number;
+}): string {
+  const blogPostsPlural = useBlogPostsPlural();
+  return translate(
+    {
+      id: 'theme.blog.tagTitle',
+      description: 'The title of the page for a blog tag',
+      message: '{nPosts} tagged with "{tagName}"',
+    },
+    {nPosts: blogPostsPlural(tag.count), tagName: tag.label},
+  );
+}
+
+export function useBlogAuthorPageTitle(author: {
+  key: string;
+  name?: string;
+  count: number;
+}): string {
+  const blogPostsPlural = useBlogPostsPlural();
+  return translate(
+    {
+      id: 'theme.blog.author.pageTitle',
+      description: 'The title of the page for a blog author',
+      message: '{authorName} - {nPosts}',
+    },
+    {
+      nPosts: blogPostsPlural(author.count),
+      authorName: author.name || author.key,
+    },
+  );
+}
+
+export const translateBlogAuthorsListPageTitle = (): string =>
+  translate({
+    id: 'theme.blog.authorsList.pageTitle',
+    message: 'Authors',
+    description: 'The title of the authors page',
+  });
+
+export function BlogAuthorsListViewAllLabel(): ReactNode {
+  return (
+    <Translate
+      id="theme.blog.authorsList.viewAll"
+      description="The label of the link targeting the blog authors page">
+      View all authors
+    </Translate>
+  );
+}
+
+export function BlogAuthorNoPostsLabel(): ReactNode {
+  return (
+    <Translate
+      id="theme.blog.author.noPosts"
+      description="The text for authors with 0 blog post">
+      This author has not written any posts yet.
+    </Translate>
+  );
+}

package/src/translations/contentVisibilityTranslations.tsx

@@ -0,0 +1,51 @@
+/**
+ * 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 type {ReactNode} from 'react';
+import Translate from '@docusaurus/Translate';
+
+export function UnlistedBannerTitle(): ReactNode {
+  return (
+    <Translate
+      id="theme.contentVisibility.unlistedBanner.title"
+      description="The unlisted content banner title">
+      Unlisted page
+    </Translate>
+  );
+}
+
+export function UnlistedBannerMessage(): ReactNode {
+  return (
+    <Translate
+      id="theme.contentVisibility.unlistedBanner.message"
+      description="The unlisted content banner message">
+      This page is unlisted. Search engines will not index it, and only users
+      having a direct link can access it.
+    </Translate>
+  );
+}
+
+export function DraftBannerTitle(): ReactNode {
+  return (
+    <Translate
+      id="theme.contentVisibility.draftBanner.title"
+      description="The draft content banner title">
+      Draft page
+    </Translate>
+  );
+}
+
+export function DraftBannerMessage(): ReactNode {
+  return (
+    <Translate
+      id="theme.contentVisibility.draftBanner.message"
+      description="The draft content banner message">
+      This page is a draft. It will only be visible in dev and be excluded from
+      the production build.
+    </Translate>
+  );
+}

package/src/translations/docsTranslations.tsx

@@ -0,0 +1,28 @@
+/**
+ * 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 {translate} from '@docusaurus/Translate';
+import {usePluralForm} from '../utils/usePluralForm';
+
+export function useDocCardDescriptionCategoryItemsPlural(): (
+  count: number,
+) => string {
+  const {selectMessage} = usePluralForm();
+  return (count: number) =>
+    selectMessage(
+      count,
+      translate(
+        {
+          message: '1 item|{count} items',
+          id: 'theme.docs.DocCard.categoryDescription.plurals',
+          description:
+            'The default description for a category card in the generated index about how many items this category includes',
+        },
+        {count},
+      ),
+    );
+}

package/src/types.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="@docusaurus/module-type-aliases" />

package/src/utils/IntlUtils.ts

@@ -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 useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+
+function useCalendar(): string {
+  const {
+    i18n: {currentLocale, localeConfigs},
+  } = useDocusaurusContext();
+  return localeConfigs[currentLocale]!.calendar;
+}
+
+export function useDateTimeFormat(
+  options: Intl.DateTimeFormatOptions = {},
+): Intl.DateTimeFormat {
+  const {
+    i18n: {currentLocale},
+  } = useDocusaurusContext();
+  const calendar = useCalendar();
+  return new Intl.DateTimeFormat(currentLocale, {
+    calendar,
+    ...options,
+  });
+}

package/src/utils/ThemeClassNames.ts

@@ -0,0 +1,119 @@
+/**
+ * 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.
+ */
+
+// Please do not modify the classnames! This is a breaking change, and annoying
+// for users!
+
+/**
+ * These class names are used to style page layouts in Docusaurus, meant to be
+ * targeted by user-provided custom CSS selectors.
+ */
+export const ThemeClassNames = {
+  page: {
+    blogListPage: 'blog-list-page',
+    blogPostPage: 'blog-post-page',
+    blogTagsListPage: 'blog-tags-list-page',
+    blogTagPostListPage: 'blog-tags-post-list-page',
+    blogAuthorsListPage: 'blog-authors-list-page',
+    blogAuthorsPostsPage: 'blog-authors-posts-page',
+
+    docsDocPage: 'docs-doc-page',
+    docsTagsListPage: 'docs-tags-list-page',
+    docsTagDocListPage: 'docs-tags-doc-list-page',
+
+    mdxPage: 'mdx-page',
+  },
+
+  // TODO Docusaurus v4: remove old classes?
+  wrapper: {
+    main: 'main-wrapper', // replaced by theme-layout-main
+    // TODO these wrapper class names are now quite useless
+    // TODO do breaking change later in 3.0
+    // we already add plugin name/id class on <html>: that's enough
+    blogPages: 'blog-wrapper',
+    docsPages: 'docs-wrapper',
+    mdxPages: 'mdx-wrapper',
+  },
+
+  common: {
+    editThisPage: 'theme-edit-this-page',
+    lastUpdated: 'theme-last-updated',
+    backToTopButton: 'theme-back-to-top-button',
+    codeBlock: 'theme-code-block',
+    admonition: 'theme-admonition',
+    unlistedBanner: 'theme-unlisted-banner',
+    draftBanner: 'theme-draft-banner',
+
+    admonitionType: (type: string) => `theme-admonition-${type}`,
+  },
+
+  announcementBar: {
+    container: 'theme-announcement-bar',
+  },
+
+  tabs: {
+    container: 'theme-tabs-container',
+  },
+
+  layout: {
+    navbar: {
+      container: 'theme-layout-navbar',
+      containerLeft: 'theme-layout-navbar-left',
+      containerRight: 'theme-layout-navbar-right',
+      mobileSidebar: {
+        container: 'theme-layout-navbar-sidebar',
+        panel: 'theme-layout-navbar-sidebar-panel',
+      },
+    },
+    main: {
+      container: 'theme-layout-main',
+    },
+    footer: {
+      container: 'theme-layout-footer',
+      column: 'theme-layout-footer-column',
+    },
+  },
+
+  /**
+   * Follows the naming convention "theme-{blog,doc,version,page}?-<suffix>"
+   */
+  docs: {
+    docVersionBanner: 'theme-doc-version-banner',
+    docVersionBadge: 'theme-doc-version-badge',
+    docBreadcrumbs: 'theme-doc-breadcrumbs',
+    docMarkdown: 'theme-doc-markdown',
+    docTocMobile: 'theme-doc-toc-mobile',
+    docTocDesktop: 'theme-doc-toc-desktop',
+    docFooter: 'theme-doc-footer',
+    docFooterTagsRow: 'theme-doc-footer-tags-row',
+    docFooterEditMetaRow: 'theme-doc-footer-edit-meta-row',
+    docSidebarContainer: 'theme-doc-sidebar-container',
+    docSidebarMenu: 'theme-doc-sidebar-menu',
+    docSidebarItemCategory: 'theme-doc-sidebar-item-category',
+    docSidebarItemLink: 'theme-doc-sidebar-item-link',
+    docSidebarItemCategoryLevel: (level: number) =>
+      `theme-doc-sidebar-item-category-level-${level}` as const,
+    docSidebarItemLinkLevel: (level: number) =>
+      `theme-doc-sidebar-item-link-level-${level}` as const,
+    // TODO add other stable classNames here
+    docCard: {
+      container: 'theme-doc-card-container',
+      heading: 'theme-doc-card-heading',
+      icon: 'theme-doc-card-icon',
+      title: 'theme-doc-card-title',
+      description: 'theme-doc-card-description',
+    },
+  },
+  blog: {
+    // TODO add other stable classNames here
+    blogFooterTagsRow: 'theme-blog-footer-tags-row',
+    blogFooterEditMetaRow: 'theme-blog-footer-edit-meta-row',
+  },
+  pages: {
+    pageFooterEditMetaRow: 'theme-pages-footer-edit-meta-row',
+  },
+} as const;

package/src/utils/accessibilityUtils.ts

@@ -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.
+ */
+
+export function prefersReducedMotion(): boolean {
+  return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}

package/src/utils/admonitionUtils.tsx

@@ -0,0 +1,44 @@
+/**
+ * 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 ReactNode, type ReactElement} from 'react';
+
+// Workaround because it's difficult in MDX v1 to provide a MDX title as props
+// See https://github.com/facebook/docusaurus/pull/7152#issuecomment-1145779682
+function extractMDXAdmonitionTitle(children: ReactNode): {
+  mdxAdmonitionTitle: ReactNode | undefined;
+  rest: ReactNode;
+} {
+  const items = React.Children.toArray(children);
+  const mdxAdmonitionTitleWrapper = items.find(
+    (item) => React.isValidElement(item) && item.type === 'mdxAdmonitionTitle',
+  ) as ReactElement<{children: ReactNode}> | undefined;
+
+  const rest = items.filter((item) => item !== mdxAdmonitionTitleWrapper);
+
+  const mdxAdmonitionTitle = mdxAdmonitionTitleWrapper?.props.children;
+
+  return {
+    mdxAdmonitionTitle,
+    rest: rest.length > 0 ? <>{rest}</> : null,
+  };
+}
+
+export function processAdmonitionProps<
+  Props extends {readonly children: ReactNode; readonly title?: ReactNode},
+>(props: Props): Props {
+  const {mdxAdmonitionTitle, rest} = extractMDXAdmonitionTitle(props.children);
+  const title = props.title ?? mdxAdmonitionTitle;
+  return {
+    ...props,
+    // Do not return "title: undefined" prop
+    // this might create unwanted props overrides when merging props
+    // For example: {...default,...props}
+    ...(title && {title}),
+    children: rest,
+  };
+}

package/src/utils/anchorUtils.module.css

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ */
+
+.anchorTargetStickyNavbar {
+  scroll-margin-top: calc(var(--ifm-navbar-height) + 0.5rem);
+}
+
+.anchorTargetHideOnScrollNavbar {
+  scroll-margin-top: 0.5rem;
+}

package/src/utils/anchorUtils.ts

@@ -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.
+ */
+
+import {useThemeConfig} from './useThemeConfig';
+import styles from './anchorUtils.module.css';
+
+/**
+ * When the navbar is sticky, this ensures that when clicking a hash link,
+ * we do not navigate to an anchor that will appear below the navbar.
+ * This happens in particular for MDX headings and footnotes.
+ *
+ * See https://github.com/facebook/docusaurus/issues/11232
+ * See also headings case https://x.com/JoshWComeau/status/1332015868725891076
+ */
+export function useAnchorTargetClassName(
+  id: string | undefined,
+): string | undefined {
+  const {
+    navbar: {hideOnScroll},
+  } = useThemeConfig();
+  if (typeof id === 'undefined') {
+    return undefined;
+  }
+  return hideOnScroll
+    ? styles.anchorTargetHideOnScrollNavbar
+    : styles.anchorTargetStickyNavbar;
+}