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

package/src/utils/tabsUtils.tsx

@@ -0,0 +1,307 @@
+/**
+ * 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, {
+  isValidElement,
+  useCallback,
+  useLayoutEffect,
+  useState,
+  useMemo,
+  createContext,
+  type ReactNode,
+  type ReactElement,
+} from 'react';
+import {useHistory} from '@docusaurus/router';
+import {useQueryStringValue} from '@docusaurus/theme-common/internal';
+import {duplicates, useStorageSlot} from '../index';
+
+/**
+ * TabValue is the "config" of a given Tab
+ * Provided through <Tabs> "values" prop or through the children <TabItem> props
+ */
+export interface TabValue {
+  readonly value: string;
+  readonly label?: string;
+  readonly attributes?: {[key: string]: unknown};
+  readonly default?: boolean;
+}
+
+export interface TabsProps {
+  readonly lazy?: boolean;
+  readonly block?: boolean;
+  readonly children: ReactNode;
+  readonly defaultValue?: string | null;
+  readonly values?: readonly TabValue[];
+  readonly groupId?: string;
+  readonly className?: string;
+  readonly queryString?: string | boolean;
+}
+
+export interface TabItemProps {
+  readonly children: ReactNode;
+  readonly value: string;
+  readonly default?: boolean;
+  readonly label?: string;
+  readonly className?: string;
+  readonly attributes?: {[key: string]: unknown};
+}
+
+export function sanitizeTabsChildren(children: ReactNode): ReactNode {
+  return React.Children.toArray(children).filter((child) => child !== '\n');
+}
+
+function extractChildrenTabValues(children: ReactNode): TabValue[] {
+  // ✅ <TabItem value="red"/> => true
+  // ✅ <CustomTabItem value="red"/> => true
+  // ❌ <RedTabItem value="tab-value"/> => requires <Tabs values> prop
+  function isTabItemWithValueProp(
+    comp: ReactElement,
+  ): comp is ReactElement<TabItemProps> {
+    const {props} = comp;
+    return !!props && typeof props === 'object' && 'value' in props;
+  }
+
+  const elements = React.Children.toArray(children).flatMap((child) => {
+    // Historical case, not sure when it happens, do we really need this?
+    if (!child) {
+      return [];
+    }
+    if (isValidElement(child) && isTabItemWithValueProp(child)) {
+      return [child];
+    }
+    // child.type.name will give non-sensical values in prod because of
+    // minification, but we assume it won't throw in prod.
+    const badChildTypeName =
+      // @ts-expect-error: guarding against unexpected cases
+      typeof child.type === 'string' ? child.type : child.type.name;
+    throw new Error(
+      `Docusaurus error: Bad <Tabs> child <${badChildTypeName}>: all children of the <Tabs> component should be <TabItem>, and every <TabItem> should have a unique "value" prop.
+If you do not want to pass on a "value" prop to the direct children of <Tabs>, you can also pass an explicit <Tabs values={...}> prop.`,
+    );
+  });
+
+  return elements.map(
+    ({props: {value, label, attributes, default: isDefault}}) => ({
+      value,
+      label,
+      attributes,
+      default: isDefault,
+    }),
+  );
+}
+
+function ensureNoDuplicateValue(values: readonly TabValue[]) {
+  const dup = duplicates(values, (a, b) => a.value === b.value);
+  if (dup.length > 0) {
+    throw new Error(
+      `Docusaurus error: Duplicate values "${dup
+        .map((a) => `'${a.value}'`)
+        .join(', ')}" found in <Tabs>. Every value needs to be unique.`,
+    );
+  }
+}
+
+function useTabValues(
+  props: Pick<TabsProps, 'values' | 'children'>,
+): readonly TabValue[] {
+  const {values: valuesProp, children} = props;
+  return useMemo(() => {
+    const values = valuesProp ?? extractChildrenTabValues(children);
+    ensureNoDuplicateValue(values);
+    return values;
+  }, [valuesProp, children]);
+}
+
+function isValidValue({
+  value,
+  tabValues,
+}: {
+  value: string | null | undefined;
+  tabValues: readonly TabValue[];
+}) {
+  return tabValues.some((a) => a.value === value);
+}
+
+function getInitialStateValue({
+  defaultValue,
+  tabValues,
+}: {
+  defaultValue: TabsProps['defaultValue'];
+  tabValues: readonly TabValue[];
+}): string {
+  if (tabValues.length === 0) {
+    throw new Error(
+      'Docusaurus error: the <Tabs> component requires at least one <TabItem> children component',
+    );
+  }
+  if (defaultValue) {
+    // Warn user about passing incorrect defaultValue as prop.
+    if (!isValidValue({value: defaultValue, tabValues})) {
+      throw new Error(
+        `Docusaurus error: The <Tabs> has a defaultValue "${defaultValue}" but none of its children has the corresponding value. Available values are: ${tabValues
+          .map((a) => a.value)
+          .join(
+            ', ',
+          )}. If you intend to show no default tab, use defaultValue={null} instead.`,
+      );
+    }
+    return defaultValue;
+  }
+  const defaultTabValue =
+    tabValues.find((tabValue) => tabValue.default) ?? tabValues[0];
+  if (!defaultTabValue) {
+    throw new Error('Unexpected error: 0 tabValues');
+  }
+  return defaultTabValue.value;
+}
+
+function getStorageKey(groupId: string | undefined) {
+  if (!groupId) {
+    return null;
+  }
+  return `docusaurus.tab.${groupId}`;
+}
+
+function getQueryStringKey({
+  queryString = false,
+  groupId,
+}: Pick<TabsProps, 'queryString' | 'groupId'>) {
+  if (typeof queryString === 'string') {
+    return queryString;
+  }
+  if (queryString === false) {
+    return null;
+  }
+  if (queryString === true && !groupId) {
+    throw new Error(
+      `Docusaurus error: The <Tabs> component groupId prop is required if queryString=true, because this value is used as the search param name. You can also provide an explicit value such as queryString="my-search-param".`,
+    );
+  }
+  return groupId ?? null;
+}
+
+function useTabQueryString({
+  queryString = false,
+  groupId,
+}: Pick<TabsProps, 'queryString' | 'groupId'>) {
+  const history = useHistory();
+  const key = getQueryStringKey({queryString, groupId});
+  const value = useQueryStringValue(key);
+
+  const setValue = useCallback(
+    (newValue: string) => {
+      if (!key) {
+        return; // no-op
+      }
+      const searchParams = new URLSearchParams(history.location.search);
+      searchParams.set(key, newValue);
+      history.replace({...history.location, search: searchParams.toString()});
+    },
+    [key, history],
+  );
+
+  return [value, setValue] as const;
+}
+
+function useTabStorage({groupId}: Pick<TabsProps, 'groupId'>) {
+  const key = getStorageKey(groupId);
+  const [value, storageSlot] = useStorageSlot(key);
+
+  const setValue = useCallback(
+    (newValue: string) => {
+      if (!key) {
+        return; // no-op
+      }
+      storageSlot.set(newValue);
+    },
+    [key, storageSlot],
+  );
+
+  return [value, setValue] as const;
+}
+
+type TabsContextValue = {
+  selectedValue: string;
+  selectValue: (value: string) => void;
+  tabValues: readonly TabValue[];
+  lazy: boolean;
+  // TODO Docusaurus v4: remove this "block" concept?
+  //  TIL about it, and afaik we never used nor documented it
+  //  See https://infima.dev/docs/components/tabs#block
+  block: boolean;
+};
+
+export function useTabsContextValue(props: TabsProps): TabsContextValue {
+  const {defaultValue, queryString = false, groupId} = props;
+  const tabValues = useTabValues(props);
+
+  const [selectedValue, setSelectedValue] = useState(() =>
+    getInitialStateValue({defaultValue, tabValues}),
+  );
+
+  const [queryStringValue, setQueryString] = useTabQueryString({
+    queryString,
+    groupId,
+  });
+
+  const [storageValue, setStorageValue] = useTabStorage({
+    groupId,
+  });
+
+  // We sync valid querystring/storage value to state on change + hydration
+  const valueToSync = (() => {
+    const value = queryStringValue ?? storageValue;
+    if (!isValidValue({value, tabValues})) {
+      return null;
+    }
+    return value;
+  })();
+  // Sync in a layout/sync effect is important, for useScrollPositionBlocker
+  // See https://github.com/facebook/docusaurus/issues/8625
+  useLayoutEffect(() => {
+    if (valueToSync) {
+      setSelectedValue(valueToSync);
+    }
+  }, [valueToSync]);
+
+  const selectValue = useCallback(
+    (newValue: string) => {
+      if (!isValidValue({value: newValue, tabValues})) {
+        throw new Error(`Can't select invalid tab value=${newValue}`);
+      }
+      setSelectedValue(newValue);
+      setQueryString(newValue);
+      setStorageValue(newValue);
+    },
+    [setQueryString, setStorageValue, tabValues],
+  );
+
+  return {
+    selectedValue,
+    selectValue,
+    tabValues,
+    lazy: props.lazy ?? false,
+    block: props.block ?? false,
+  };
+}
+
+const TabsContext = createContext<TabsContextValue | null>(null);
+
+export function useTabs(): TabsContextValue {
+  const contextValue = React.useContext(TabsContext);
+  if (!contextValue) {
+    throw new Error('useTabsContext() must be used within a Tabs component');
+  }
+  return contextValue;
+}
+
+export function TabsProvider(props: {
+  children: ReactNode;
+  value: TabsContextValue;
+}): ReactNode {
+  return <TabsContext value={props.value}>{props.children}</TabsContext>;
+}

package/src/utils/tagsUtils.tsx

@@ -0,0 +1,61 @@
+/**
+ * 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 type {TagsListItem} from '@docusaurus/utils';
+
+export const translateTagsPageTitle = (): string =>
+  translate({
+    id: 'theme.tags.tagsPageTitle',
+    message: 'Tags',
+    description: 'The title of the tag list page',
+  });
+
+export function TagsPageLinkLabel(): ReactNode {
+  return (
+    <Translate
+      id="theme.tags.tagsPageLink"
+      description="The label of the link targeting the tag list page">
+      View all tags
+    </Translate>
+  );
+}
+
+export type TagLetterEntry = {letter: string; tags: TagsListItem[]};
+
+function getTagLetter(tag: string): string {
+  return tag[0]!.toUpperCase();
+}
+
+/**
+ * Takes a list of tags (as provided by the content plugins), and groups them by
+ * their initials.
+ */
+export function listTagsByLetters(
+  tags: readonly TagsListItem[],
+): TagLetterEntry[] {
+  const groups: {[initial: string]: TagsListItem[]} = {};
+  Object.values(tags).forEach((tag) => {
+    const initial = getTagLetter(tag.label);
+    groups[initial] ??= [];
+    groups[initial]!.push(tag);
+  });
+
+  return (
+    Object.entries(groups)
+      // Sort letters
+      .sort(([letter1], [letter2]) => letter1.localeCompare(letter2))
+      .map(([letter, letterTags]) => {
+        // Sort tags inside a letter
+        const sortedTags = letterTags.sort((tag1, tag2) =>
+          tag1.label.localeCompare(tag2.label),
+        );
+        return {letter, tags: sortedTags};
+      })
+  );
+}

package/src/utils/titleFormatterUtils.tsx

@@ -0,0 +1,120 @@
+/**
+ * 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 {createContext, useContext} from 'react';
+import type {ReactNode} from 'react';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import useRouteContext from '@docusaurus/useRouteContext';
+import {ReactContextError} from './reactUtils';
+
+type TitleFormatterParams = {
+  /**
+   * The page title to format
+   * Usually provided with these APIs:
+   * - <PageMetadata title={title}>
+   * - useTitleFormatter().format(title)
+   */
+  title: string;
+
+  /**
+   * The siteConfig.title value
+   */
+  siteTitle: string;
+
+  /**
+   * The siteConfig.titleDelimiter value
+   */
+  titleDelimiter: string;
+
+  /**
+   * The plugin that created the page you are on
+   */
+  plugin: {
+    id: string;
+    name: string;
+  };
+};
+
+/**
+ * This is the full formatting function, including all useful params
+ * Can be customized through React context with the provider
+ */
+export type TitleFormatterFn = (params: TitleFormatterParams) => string;
+
+/**
+ * The default formatter is provided in params for convenience
+ */
+export type TitleFormatterFnWithDefault = (
+  params: TitleFormatterParams & {
+    defaultFormatter: (params: TitleFormatterParams) => string;
+  },
+) => string;
+
+export const TitleFormatterFnDefault: TitleFormatterFn = ({
+  title,
+  siteTitle,
+  titleDelimiter,
+}): string => {
+  const trimmedTitle = title?.trim();
+  if (!trimmedTitle || trimmedTitle === siteTitle) {
+    return siteTitle;
+  }
+  return `${trimmedTitle} ${titleDelimiter} ${siteTitle}`;
+};
+
+/**
+ * This is the simpler API exposed to theme/users
+ */
+type TitleFormatter = {format: (title: string) => string};
+
+const TitleFormatterContext = createContext<TitleFormatterFnWithDefault | null>(
+  null,
+);
+
+export function TitleFormatterProvider({
+  formatter,
+  children,
+}: {
+  children: ReactNode;
+  formatter: TitleFormatterFnWithDefault;
+}): ReactNode {
+  return (
+    <TitleFormatterContext value={formatter}>{children}</TitleFormatterContext>
+  );
+}
+
+function useTitleFormatterContext() {
+  const value = useContext(TitleFormatterContext);
+  if (value === null) {
+    throw new ReactContextError('TitleFormatterProvider');
+  }
+  return value;
+}
+
+/**
+ * Returns a function to format the page title
+ */
+export function useTitleFormatter(): TitleFormatter {
+  const formatter = useTitleFormatterContext();
+  const {siteConfig} = useDocusaurusContext();
+  const {title: siteTitle, titleDelimiter} = siteConfig;
+
+  // Unfortunately we can only call this hook here, not in the provider
+  // Route context can't be accessed in any provider applied above the router
+  const {plugin} = useRouteContext();
+
+  return {
+    format: (title: string) =>
+      formatter({
+        title,
+        siteTitle,
+        titleDelimiter,
+        plugin,
+        defaultFormatter: TitleFormatterFnDefault,
+      }),
+  };
+}

package/src/utils/tocUtils.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.
+ */
+
+import {useMemo} from 'react';
+import type {TOCItem} from '@docusaurus/mdx-loader';
+
+export type TOCTreeNode = {
+  readonly value: string;
+  readonly id: string;
+  readonly level: number;
+  readonly children: readonly TOCTreeNode[];
+};
+
+function treeifyTOC(flatTOC: readonly TOCItem[]): TOCTreeNode[] {
+  const headings = flatTOC.map((heading) => ({
+    ...heading,
+    parentIndex: -1,
+    children: [] as TOCTreeNode[],
+  }));
+
+  // Keep track of which previous index would be the current heading's direct
+  // parent. Each entry <i> is the last index of the `headings` array at heading
+  // level <i>. We will modify these indices as we iterate through all headings.
+  // e.g. if an ### H3 was last seen at index 2, then prevIndexForLevel[3] === 2
+  // indices 0 and 1 will remain unused.
+  const prevIndexForLevel = Array<number>(7).fill(-1);
+
+  headings.forEach((curr, currIndex) => {
+    // Take the last seen index for each ancestor level. the highest index will
+    // be the direct ancestor of the current heading.
+    const ancestorLevelIndexes = prevIndexForLevel.slice(2, curr.level);
+    curr.parentIndex = Math.max(...ancestorLevelIndexes);
+    // Mark that curr.level was last seen at the current index.
+    prevIndexForLevel[curr.level] = currIndex;
+  });
+
+  const rootNodes: TOCTreeNode[] = [];
+
+  // For a given parentIndex, add each Node into that parent's `children` array
+  headings.forEach((heading) => {
+    const {parentIndex, ...rest} = heading;
+    if (parentIndex >= 0) {
+      headings[parentIndex]!.children.push(rest);
+    } else {
+      rootNodes.push(rest);
+    }
+  });
+  return rootNodes;
+}
+
+/**
+ * Takes a flat TOC list (from the MDX loader) and treeifies it into what the
+ * TOC components expect. Memoized for performance.
+ */
+export function useTreeifiedTOC(toc: TOCItem[]): readonly TOCTreeNode[] {
+  return useMemo(() => treeifyTOC(toc), [toc]);
+}
+
+function filterTOC({
+  toc,
+  minHeadingLevel,
+  maxHeadingLevel,
+}: {
+  toc: readonly TOCTreeNode[];
+  minHeadingLevel: number;
+  maxHeadingLevel: number;
+}): TOCTreeNode[] {
+  function isValid(item: TOCTreeNode) {
+    return item.level >= minHeadingLevel && item.level <= maxHeadingLevel;
+  }
+
+  return toc.flatMap((item) => {
+    const filteredChildren = filterTOC({
+      toc: item.children,
+      minHeadingLevel,
+      maxHeadingLevel,
+    });
+    if (isValid(item)) {
+      return [
+        {
+          ...item,
+          children: filteredChildren,
+        },
+      ];
+    }
+    return filteredChildren;
+  });
+}
+
+/**
+ * Takes a flat TOC list (from the MDX loader) and treeifies it into what the
+ * TOC components expect, applying the `minHeadingLevel` and `maxHeadingLevel`.
+ * Memoized for performance.
+ *
+ * **Important**: this is not the same as `useTreeifiedTOC(toc.filter(...))`,
+ * because we have to filter the TOC after it has been treeified. This is mostly
+ * to ensure that weird TOC structures preserve their semantics. For example, an
+ * h3-h2-h4 sequence should not be treeified as an "h3 > h4" hierarchy with
+ * min=3, max=4, but should rather be "[h3, h4]" (since the h2 heading has split
+ * the two headings and they are not parent-children)
+ */
+export function useFilteredAndTreeifiedTOC({
+  toc,
+  minHeadingLevel,
+  maxHeadingLevel,
+}: {
+  toc: readonly TOCItem[];
+  minHeadingLevel: number;
+  maxHeadingLevel: number;
+}): readonly TOCTreeNode[] {
+  return useMemo(
+    () => filterTOC({toc: treeifyTOC(toc), minHeadingLevel, maxHeadingLevel}),
+    [toc, minHeadingLevel, maxHeadingLevel],
+  );
+}

package/src/utils/useAlternatePageUtils.ts

@@ -0,0 +1,80 @@
+/**
+ * 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';
+import {useLocation} from '@docusaurus/router';
+import {applyTrailingSlash} from '@docusaurus/utils-common';
+import type {I18nLocaleConfig} from '@docusaurus/types';
+
+/**
+ * Permits to obtain the url of the current page in another locale, useful to
+ * generate hreflang meta headers etc...
+ *
+ * @see https://developers.google.com/search/docs/advanced/crawling/localized-versions
+ */
+export function useAlternatePageUtils(): {
+  /**
+   * Everything (pathname, base URL, etc.) is read from the context. Just tell
+   * it which locale to link to and it will give you the alternate link for the
+   * current page.
+   */
+  createUrl: ({
+    /** The locale name to link to. */
+    locale,
+    /**
+     * For hreflang SEO headers, we need it to be fully qualified (full
+     * protocol/domain/path...); but for locale dropdowns, using a pathname is
+     * good enough.
+     */
+    fullyQualified,
+  }: {
+    locale: string;
+    fullyQualified: boolean;
+  }) => string;
+} {
+  const {
+    siteConfig: {baseUrl, trailingSlash},
+    i18n: {localeConfigs},
+  } = useDocusaurusContext();
+
+  // TODO using useLocation().pathname is not a super idea
+  // See https://github.com/facebook/docusaurus/issues/9170
+  const {pathname} = useLocation();
+
+  const canonicalPathname = applyTrailingSlash(pathname, {
+    trailingSlash,
+    baseUrl,
+  });
+
+  // Canonical pathname, without the baseUrl of the current locale
+  const pathnameSuffix = canonicalPathname.replace(baseUrl, '');
+
+  function getLocaleConfig(locale: string): I18nLocaleConfig {
+    const localeConfig = localeConfigs[locale];
+    if (!localeConfig) {
+      throw new Error(
+        `Unexpected Docusaurus bug, no locale config found for locale=${locale}`,
+      );
+    }
+    return localeConfig;
+  }
+
+  function createUrl({
+    locale,
+    fullyQualified,
+  }: {
+    locale: string;
+    fullyQualified: boolean;
+  }) {
+    const localeConfig = getLocaleConfig(locale);
+    const newUrl = `${fullyQualified ? localeConfig.url : ''}`;
+    const newBaseUrl = localeConfig.baseUrl;
+    return `${newUrl}${newBaseUrl}${pathnameSuffix}`;
+  }
+
+  return {createUrl};
+}

package/src/utils/useLocalPathname.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 {useLocation} from '@docusaurus/router';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+
+/**
+ * Get the pathname of current route, without the optional site baseUrl.
+ * - `/docs/myDoc` => `/docs/myDoc`
+ * - `/baseUrl/docs/myDoc` => `/docs/myDoc`
+ */
+export function useLocalPathname(): string {
+  const {
+    siteConfig: {baseUrl},
+  } = useDocusaurusContext();
+  const {pathname} = useLocation();
+  return pathname.replace(baseUrl, '/');
+}