@redocly/theme 0.70.0-next.9 → 0.71.0-next.0

package/src/core/hooks/use-active-heading.ts

@@ -0,0 +1,355 @@
+import { useState, useEffect, useRef, useCallback } from 'react';
+import { useLocation } from 'react-router';
+
+import { enhancedSmoothstep } from '../utils';
+import { HEADING_ANCHOR_CLASS } from '../constants';
+
+type HeadingEntry = {
+  [key: string]: IntersectionObserverEntry;
+};
+
+type ClickScroll = {
+  target: HTMLElement;
+  scrollMargin: number;
+  closestDistance: number;
+  reached: boolean;
+};
+
+const TARGET_TOLERANCE = 2;
+
+export function useActiveHeading(
+  contentElement: HTMLDivElement | null,
+  displayedHeadings?: Array<{ id: string; depth: number } | null>,
+): { heading: string | undefined; handleHeadingClick: (headingId: string) => void } {
+  const [heading, setHeading] = useState<string | undefined>(undefined);
+  const [headingElements, setHeadingElements] = useState<HTMLElement[]>([]);
+  const headingElementsRef = useRef<HeadingEntry>({});
+  const displayedHeadingsRef = useRef(displayedHeadings);
+  const lockObserver = useRef<boolean>(false);
+  const clickScroll = useRef<ClickScroll | null>(null);
+  const location = useLocation();
+
+  useEffect(() => {
+    setHeading(undefined);
+    headingElementsRef.current = {};
+    clickScroll.current = null;
+    lockObserver.current = false;
+  }, [location.pathname]);
+
+  useEffect(() => {
+    displayedHeadingsRef.current = displayedHeadings;
+  }, [displayedHeadings]);
+
+  const getVisibleHeadings = () => {
+    const visibleHeadings: IntersectionObserverEntry[] = [];
+
+    for (const key in headingElementsRef.current) {
+      const headingElement = headingElementsRef.current[key];
+
+      if (headingElement.isIntersecting) {
+        visibleHeadings.push(headingElement);
+      }
+    }
+
+    return visibleHeadings;
+  };
+
+  const isTopOfPage = () => window.scrollY <= 50;
+
+  // Returns viewport ratio for intersection observer based on screen height
+  const getViewportRatio = () => {
+    const vh = window.innerHeight;
+    if (vh >= 1400) return 0.4;
+    if (vh >= 1000) return 0.3;
+    return 0.25;
+  };
+
+  const getIndexFromId = useCallback(
+    (id: string) => {
+      return headingElements.findIndex((item) => item.id === id);
+    },
+    [headingElements],
+  );
+
+  const findHeaders = (allContent: HTMLDivElement) => {
+    const allHeaders = allContent.querySelectorAll<HTMLElement>(`.${HEADING_ANCHOR_CLASS}`);
+    const headers = Array.from(allHeaders);
+
+    if (displayedHeadingsRef.current && displayedHeadingsRef.current.length > 0) {
+      // Resolve targets by id so anchors that are not headings (e.g. numbered
+      // list items with a lifted headline) can be scrolled to and tracked.
+      return displayedHeadingsRef.current
+        .map((heading) =>
+          heading?.id ? allContent.querySelector<HTMLElement>(`[id="${heading.id}"]`) : null,
+        )
+        .filter((element): element is HTMLElement => element !== null);
+    }
+
+    return headers;
+  };
+
+  const calculateVirtualPositions = useCallback((headers: HTMLElement[]) => {
+    if (!headers.length) return {};
+
+    const navbarHeight = document.querySelector('nav')?.getBoundingClientRect().height || 0;
+    const viewportHeight = window.innerHeight;
+    const triggerOffset = navbarHeight + viewportHeight * 0.25;
+
+    const lastHeader = headers[headers.length - 1];
+    const lastHeaderTop = lastHeader.offsetTop;
+    const maxScrollableHeight = document.body.scrollHeight - viewportHeight;
+
+    const requiredUplift = Math.max(0, lastHeaderTop - maxScrollableHeight + triggerOffset);
+
+    const virtualPositions: Record<string, number> = {};
+
+    for (let i = 0; i < headers.length; i++) {
+      const header = headers[i];
+      const headerTop = header.offsetTop;
+
+      const normalizedPosition = headers.length === 1 ? 0 : i / (headers.length - 1);
+
+      const adjustmentFactor = enhancedSmoothstep(normalizedPosition, 0.4);
+
+      const uplift = requiredUplift * adjustmentFactor;
+      const virtualTop = headerTop - uplift;
+
+      virtualPositions[header.id] = virtualTop;
+    }
+
+    return virtualPositions;
+  }, []);
+
+  const getTriggerOffset = useCallback(() => {
+    const navbarHeight = document.querySelector('nav')?.getBoundingClientRect().height || 0;
+    return navbarHeight + window.innerHeight * getViewportRatio();
+  }, []);
+
+  const findActiveHeaderByVirtualPosition = useCallback(
+    (headers: HTMLElement[], scrollY: number, triggerOffset: number) => {
+      const virtualPositions = calculateVirtualPositions(headers);
+
+      let activeHeader = headers[0];
+      for (const header of headers) {
+        const virtualTop = virtualPositions[header.id] || header.offsetTop;
+        if (virtualTop <= scrollY + triggerOffset) {
+          activeHeader = header;
+        } else {
+          break;
+        }
+      }
+      return activeHeader;
+    },
+    [calculateVirtualPositions],
+  );
+
+  const intersectionCallback = useCallback(
+    (entries: IntersectionObserverEntry[]) => {
+      headingElementsRef.current = entries.reduce(
+        (map: HeadingEntry, entry: IntersectionObserverEntry) => {
+          map[entry.target.id] = entry;
+          return map;
+        },
+        headingElementsRef.current,
+      );
+
+      if (lockObserver.current) {
+        return;
+      }
+
+      if (isTopOfPage()) {
+        const newHeading = headingElements[0]?.id || undefined;
+        setHeading(newHeading);
+        return;
+      }
+
+      const visibleHeadings = getVisibleHeadings();
+      if (!visibleHeadings.length) {
+        const triggerOffset = getTriggerOffset();
+
+        if (isTopOfPage()) {
+          setHeading(headingElements[0]?.id || undefined);
+          return;
+        }
+
+        const totalHeight = window.scrollY + window.innerHeight;
+        if (totalHeight >= document.body.scrollHeight - 10) {
+          setHeading(headingElements[headingElements.length - 1]?.id || undefined);
+          return;
+        }
+
+        const activeHeader = findActiveHeaderByVirtualPosition(
+          headingElements,
+          window.scrollY,
+          triggerOffset,
+        );
+        setHeading(activeHeader.id);
+        return;
+      }
+
+      if (visibleHeadings.length === 1) {
+        setHeading(visibleHeadings[0].target.id);
+        return;
+      }
+
+      visibleHeadings.sort((a, b) => {
+        return getIndexFromId(a.target.id) - getIndexFromId(b.target.id);
+      });
+
+      const firstVisibleHeading = visibleHeadings[0];
+
+      if (getIndexFromId(firstVisibleHeading.target.id) === 0 && isTopOfPage()) {
+        setHeading(firstVisibleHeading.target.id);
+        return;
+      }
+
+      const totalHeight = scrollY + window.innerHeight;
+      if (totalHeight >= document.body.scrollHeight - 10) {
+        setHeading(visibleHeadings[visibleHeadings.length - 1].target.id);
+        return;
+      }
+
+      setHeading(visibleHeadings[0].target.id);
+    },
+    [getIndexFromId, headingElements, getTriggerOffset, findActiveHeaderByVirtualPosition],
+  );
+
+  const releaseClickScroll = useCallback(() => {
+    clickScroll.current = null;
+    lockObserver.current = false;
+  }, []);
+
+  const trackClickScroll = useCallback(() => {
+    const clickScrollState = clickScroll.current;
+    if (!clickScrollState) {
+      return;
+    }
+
+    const { top } = clickScrollState.target.getBoundingClientRect();
+
+    if (clickScrollState.reached) {
+      if (top >= 0 && top <= getTriggerOffset()) {
+        return;
+      }
+    } else {
+      const distance = Math.abs(top - clickScrollState.scrollMargin);
+
+      if (distance <= TARGET_TOLERANCE) {
+        clickScrollState.reached = true;
+        return;
+      }
+
+      if (distance <= clickScrollState.closestDistance + TARGET_TOLERANCE) {
+        clickScrollState.closestDistance = Math.min(clickScrollState.closestDistance, distance);
+        return;
+      }
+    }
+
+    releaseClickScroll();
+    intersectionCallback([]);
+  }, [releaseClickScroll, intersectionCallback, getTriggerOffset]);
+
+  const handleHeadingClick = useCallback(
+    (headingId: string) => {
+      releaseClickScroll();
+      setHeading(headingId);
+
+      const target =
+        document.getElementById(headingId) || headingElements.find((el) => el.id === headingId);
+
+      if (!target?.scrollIntoView) {
+        return;
+      }
+
+      target.scrollIntoView({ behavior: 'smooth', block: 'start' });
+
+      if (!target.getClientRects().length) {
+        return;
+      }
+
+      const scrollMargin = parseFloat(getComputedStyle(target).scrollMarginTop) || 0;
+      const distance = Math.abs(target.getBoundingClientRect().top - scrollMargin);
+
+      lockObserver.current = true;
+      clickScroll.current = {
+        target,
+        scrollMargin,
+        closestDistance: distance,
+        reached: distance <= TARGET_TOLERANCE,
+      };
+    },
+    [headingElements, releaseClickScroll],
+  );
+
+  useEffect(() => {
+    if (!contentElement) {
+      return;
+    }
+    const headers = findHeaders(contentElement);
+    // oxlint-disable-next-line react-you-might-not-need-an-effect/no-chain-state-updates -- headings and the initial active heading come from DOM queries and scroll measurement, available only after layout
+    setHeadingElements(headers);
+
+    if (headers.length > 0 && !heading) {
+      if (isTopOfPage()) {
+        // oxlint-disable-next-line react-you-might-not-need-an-effect/no-chain-state-updates -- see above
+        setHeading(headers[0].id);
+      } else {
+        const totalHeight = scrollY + window.innerHeight;
+        if (totalHeight >= document.body.scrollHeight - 10) {
+          // oxlint-disable-next-line react-you-might-not-need-an-effect/no-chain-state-updates -- see above
+          setHeading(headers[headers.length - 1]?.id || undefined);
+        } else {
+          const triggerOffset = getTriggerOffset();
+          const activeHeader = findActiveHeaderByVirtualPosition(headers, scrollY, triggerOffset);
+          // oxlint-disable-next-line react-you-might-not-need-an-effect/no-chain-state-updates -- see above
+          setHeading(activeHeader.id);
+        }
+      }
+    }
+  }, [
+    contentElement,
+    location,
+    heading,
+    calculateVirtualPositions,
+    getTriggerOffset,
+    findActiveHeaderByVirtualPosition,
+  ]);
+
+  useEffect(() => {
+    if (!headingElements?.length) {
+      return;
+    }
+    headingElementsRef.current = {};
+
+    const triggerOffset = getTriggerOffset();
+
+    const observer = new IntersectionObserver(intersectionCallback, {
+      rootMargin: `-${triggerOffset}px 0px -${window.innerHeight * getViewportRatio()}px 0px`,
+      threshold: [0, 0.1, 0.3, 0.5, 0.7, 1],
+    });
+
+    headingElements.forEach((element) => {
+      observer.observe(element);
+    });
+
+    const handleScroll = () => {
+      if (clickScroll.current) {
+        trackClickScroll();
+        return;
+      }
+
+      if (isTopOfPage()) {
+        setHeading(headingElements[0]?.id || undefined);
+      }
+    };
+
+    window.addEventListener('scroll', handleScroll, { passive: true });
+
+    return () => {
+      observer.disconnect();
+      window.removeEventListener('scroll', handleScroll);
+    };
+  }, [headingElements, intersectionCallback, getTriggerOffset, trackClickScroll]);
+
+  return { heading, handleHeadingClick };
+}

package/src/core/hooks/use-active-page-version.ts

@@ -0,0 +1,9 @@
+import { useThemeHooks } from './use-theme-hooks';
+
+export function useActivePageVersion(): string | undefined {
+  const { usePageVersions } = useThemeHooks();
+  const { versions } = usePageVersions();
+  const activeVersion = versions.find((version) => version.active);
+
+  return activeVersion?.version;
+}

package/src/core/hooks/use-active-section-id.ts

@@ -0,0 +1,83 @@
+import { useEffect, useState, useMemo } from 'react';
+import throttle from 'lodash.throttle';
+
+import type { Location } from 'react-router';
+
+import { useNavbarHeight } from './use-navbar-height';
+import { IS_BROWSER } from '../utils/dom';
+
+export type UseActiveSectionIdReturnType = string;
+
+/** Px below the top where the active section is read (accounts for next-section visibility). */
+export const SECTION_READING_LINE_OFFSET = 150;
+
+export function useActiveSectionId(
+  location: Location,
+  hasOverviewPage = false,
+  withNavbar = true,
+  sectionOffset = SECTION_READING_LINE_OFFSET,
+): UseActiveSectionIdReturnType {
+  const [itemId, setItemId] = useState<string>('');
+  const navbarHeight = useNavbarHeight(location);
+  const heightOffset = (withNavbar ? navbarHeight : 0) + sectionOffset;
+
+  const scrollListener = useMemo(
+    () =>
+      throttle(() => {
+        if (!IS_BROWSER) {
+          return;
+        }
+
+        const sections = document.querySelectorAll('[data-section-id]');
+        if (sections.length < 2) {
+          setItemId('');
+          return;
+        }
+
+        if (window.scrollY <= 0) {
+          setItemId(sections[0].getAttribute('data-section-id') || '');
+          return;
+        }
+
+        for (let i = 0; i < sections.length; i++) {
+          const section = sections[i];
+          const rect = section.getBoundingClientRect();
+          if (rect.y < heightOffset && rect.bottom > heightOffset) {
+            if (isSkippedContent(section)) continue;
+            setItemId(section.getAttribute('data-section-id') || '');
+            return;
+          }
+        }
+        if (hasOverviewPage) {
+          setItemId('');
+        }
+      }, 150),
+    [heightOffset, hasOverviewPage],
+  );
+
+  useEffect(() => {
+    if (!IS_BROWSER) {
+      return;
+    }
+
+    window.addEventListener('scroll', scrollListener, { capture: false });
+    const initialRead = setTimeout(() => {
+      scrollListener();
+    }, 10);
+
+    return () => {
+      clearTimeout(initialRead);
+      scrollListener.cancel();
+      window.removeEventListener('scroll', scrollListener);
+    };
+  }, [location, heightOffset, scrollListener]);
+
+  return itemId;
+}
+
+function isSkippedContent(element: Element): boolean {
+  return (
+    typeof element.checkVisibility === 'function' &&
+    !element.checkVisibility({ contentVisibilityAuto: true })
+  );
+}

package/src/core/hooks/use-anchor-positioning.ts

@@ -0,0 +1,22 @@
+import { useEffect, useState } from 'react';
+
+export const useAnchorPositioning = (): { isSupported: boolean } => {
+  const [isSupported, setIsSupported] = useState(false);
+
+  useEffect(() => {
+    setIsSupported(isAnchorPositioningSupported());
+  }, []);
+
+  return { isSupported };
+};
+
+function isAnchorPositioningSupported(): boolean {
+  if (typeof CSS === 'undefined' || typeof CSS.supports !== 'function') {
+    return false;
+  }
+  return (
+    CSS.supports('anchor-name: --a') &&
+    CSS.supports('position-anchor: --a') &&
+    CSS.supports('top: anchor(top)')
+  );
+}

package/src/core/hooks/use-banner-telemetry.ts

@@ -0,0 +1,57 @@
+import { useMemo } from 'react';
+
+import type { DisplayBanner } from '@redocly/theme/components/Banner/Banner';
+
+import { useThemeHooks } from './use-theme-hooks';
+import { getBaseDataAttributes } from '../utils/telemetry/get-base-data-attributes';
+
+const noop = (): void => {};
+const noopLink = (_href: string): void => {};
+
+export type BannerTelemetryActions = {
+  sendBannerViewedMessage: () => void;
+  sendBannerDismissedMessage: () => void;
+  sendBannerLinkClickedMessage: (href: string) => void;
+};
+
+export function useBannerTelemetry(
+  displayBanner: DisplayBanner | undefined,
+): BannerTelemetryActions {
+  const { useTelemetry } = useThemeHooks();
+  const telemetry = useTelemetry();
+
+  return useMemo(() => {
+    if (!displayBanner) {
+      return {
+        sendBannerViewedMessage: noop,
+        sendBannerDismissedMessage: noop,
+        sendBannerLinkClickedMessage: noopLink,
+      };
+    }
+
+    const payload = {
+      ...getBaseDataAttributes<'bannerId', 'banner', 'urn:redocly:realm:ui:banner:bannerId'>(
+        'bannerId',
+        'banner',
+      ),
+      trackingId: displayBanner.trackingId,
+      hash: displayBanner.hash,
+      color: displayBanner.color,
+      target: displayBanner.target,
+      dismissible: displayBanner.dismissible,
+    };
+
+    return {
+      sendBannerViewedMessage: () => {
+        telemetry.sendBannerViewedMessage([payload]);
+      },
+      sendBannerDismissedMessage: () => {
+        const { dismissible: _, ...dismissedPayload } = payload;
+        telemetry.sendBannerDismissedMessage([dismissedPayload]);
+      },
+      sendBannerLinkClickedMessage: (href: string) => {
+        telemetry.sendBannerLinkClickedMessage([{ ...payload, href }]);
+      },
+    };
+  }, [displayBanner, telemetry]);
+}

package/src/core/hooks/use-codeblock-tabs-controls.ts

@@ -0,0 +1,67 @@
+import { useEffect, useState, useCallback, useMemo } from 'react';
+
+import type { CodeBlockItems } from '../../components/CodeBlock/CodeBlock';
+
+type CodeBlockTabsProps = {
+  tabs: CodeBlockItems;
+  containerRef: React.RefObject<HTMLDivElement | null>;
+  tabRefs: React.RefObject<HTMLButtonElement[]>;
+};
+
+export function useCodeBlockTabsControls({ tabs, containerRef, tabRefs }: CodeBlockTabsProps) {
+  const [showControls, setShowControls] = useState(false);
+
+  const tabsWidth = useMemo(
+    () =>
+      tabRefs?.current?.reduce((acc, tabRef) => {
+        return tabRef ? acc + tabRef.offsetWidth : acc;
+      }, 0) || 0,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [tabRefs?.current?.length],
+  );
+
+  const { currentIndex, isFirstTab, isLastTab } = useMemo(() => {
+    const currentIndex = tabs.items.findIndex((file) => file.name === tabs.value);
+    return {
+      currentIndex,
+      isFirstTab: currentIndex === 0,
+      isLastTab: currentIndex === tabs.items.length - 1,
+    };
+  }, [tabs]);
+
+  useEffect(() => {
+    if (containerRef.current) {
+      const container = containerRef.current;
+      const resizeObserver = new ResizeObserver((entries) => {
+        const containerWidth = entries[0].contentRect.width;
+
+        setShowControls(tabsWidth > containerWidth);
+      });
+
+      resizeObserver.observe(container);
+
+      return () => {
+        resizeObserver.unobserve(container as HTMLDivElement);
+      };
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [containerRef.current]);
+
+  const handlePrevTab = useCallback(() => {
+    if (!isFirstTab) {
+      const prevTab = tabs.items[currentIndex - 1].name;
+      tabs.onChange(prevTab);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [currentIndex]);
+
+  const handleNextTab = useCallback(() => {
+    if (!isLastTab) {
+      const nextTab = tabs.items[currentIndex + 1].name;
+      tabs.onChange(nextTab);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [currentIndex]);
+
+  return { showControls, handlePrevTab, handleNextTab };
+}

package/src/core/hooks/use-color-switcher.ts

@@ -0,0 +1,76 @@
+import { useMemo, useCallback } from 'react';
+
+import { useMount } from '@redocly/theme/core/hooks';
+
+import { useThemeConfig } from './use-theme-config';
+import { useThemeHooks } from './use-theme-hooks';
+import { createStore, useStore } from './use-store';
+import { DEFAULT_COLOR_MODES } from '../constants';
+import { generateBeforeAfterContext } from '../utils';
+
+const COLOR_MODE_KEY = 'colorSchema';
+const colorModeStore = createStore<string>({
+  storageKey: COLOR_MODE_KEY,
+});
+
+export const useColorSwitcher = () => {
+  const themeSettings = useThemeConfig();
+  const { useTelemetry } = useThemeHooks();
+  const telemetry = useTelemetry();
+  const themeColorMode = themeSettings.colorMode;
+
+  const modes = useMemo(
+    () => themeColorMode?.modes || [DEFAULT_COLOR_MODES.LIGHT, DEFAULT_COLOR_MODES.DARK],
+    [themeColorMode],
+  );
+
+  const defaultMode = modes[0] || DEFAULT_COLOR_MODES.LIGHT;
+
+  const [activeColorMode, setActiveColorMode] = useStore<string>(colorModeStore, defaultMode);
+
+  useMount(() => {
+    const activeMode = Array.from(document.documentElement.classList).find((c) =>
+      modes.includes(c),
+    );
+    setActiveColorMode(activeMode || defaultMode);
+  });
+
+  const switchColorMode = (mode?: string): void => {
+    if (mode && !modes.includes(mode)) {
+      return;
+    }
+
+    const activeIndex = modes.indexOf(activeColorMode);
+    const newMode = mode || (activeIndex < modes.length - 1 ? modes[activeIndex + 1] : modes[0]);
+
+    const root = document.documentElement;
+
+    modes.forEach((mode) => root.classList.remove(mode));
+    root.classList.add(newMode, 'notransition');
+
+    window.requestAnimationFrame(() => {
+      root.classList.remove('notransition');
+    });
+    telemetry.sendColorModeSwitchedMessage([
+      ...generateBeforeAfterContext<'sendColorModeSwitchedMessage'>(
+        'colorMode',
+        'button',
+        { mode: activeColorMode },
+        { mode: newMode },
+      ),
+    ]);
+    setActiveColorMode(newMode);
+  };
+
+  /**
+   * @deprecated color mode is automatically initialized when the hook is mounted
+   */
+  const initActiveColorMode = useCallback(() => {}, []);
+
+  return {
+    initActiveColorMode,
+    isSwitcherHidden: themeColorMode?.hide,
+    switchColorMode,
+    activeColorMode,
+  };
+};