api-ref: added syncing between code tabs (#4786)

* api-ref: added syncing between code tabs

* updated comment

* resolve metadata warning

* fix colors

www/api-reference/hooks/scroll-utils.tsx

@@ -0,0 +1,332 @@
+"use client"
+
+/* Copied from Docusaurus to maintain scroll position on re-renders. Useful when content of the page is updated dynamically */
+
+/**
+ * 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, {
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  type ReactNode,
+} from "react"
+
+type EventFunc = (...args: never[]) => unknown
+
+export function useEvent<T extends EventFunc>(callback: T): T {
+  const ref = useRef<T>(callback)
+
+  useLayoutEffect(() => {
+    ref.current = callback
+  }, [callback])
+
+  // @ts-expect-error: TS is right that this callback may be a supertype of T,
+  // but good enough for our use
+  return useCallback<T>((...args) => ref.current(...args), [])
+}
+
+/**
+ * Gets `value` from the last render.
+ */
+export function usePrevious<T>(value: T): T | undefined {
+  const ref = useRef<T>()
+
+  useLayoutEffect(() => {
+    ref.current = value
+  })
+
+  return ref.current
+}
+
+type ScrollController = {
+  /** A boolean ref tracking whether scroll events are enabled. */
+  scrollEventsEnabledRef: React.MutableRefObject<boolean>
+  /** Enable scroll events in `useScrollPosition`. */
+  enableScrollEvents: () => void
+  /** Disable scroll events in `useScrollPosition`. */
+  disableScrollEvents: () => void
+}
+
+function useScrollControllerContextValue(): ScrollController {
+  const scrollEventsEnabledRef = useRef(true)
+
+  return useMemo(
+    () => ({
+      scrollEventsEnabledRef,
+      enableScrollEvents: () => {
+        scrollEventsEnabledRef.current = true
+      },
+      disableScrollEvents: () => {
+        scrollEventsEnabledRef.current = false
+      },
+    }),
+    []
+  )
+}
+
+const ScrollMonitorContext = React.createContext<ScrollController | undefined>(
+  undefined
+)
+
+export function ScrollControllerProvider({
+  children,
+}: {
+  children: ReactNode
+}): JSX.Element {
+  const value = useScrollControllerContextValue()
+  return (
+    <ScrollMonitorContext.Provider value={value}>
+      {children}
+    </ScrollMonitorContext.Provider>
+  )
+}
+
+/**
+ * We need a way to update the scroll position while ignoring scroll events
+ * so as not to toggle Navbar/BackToTop visibility.
+ *
+ * This API permits to temporarily disable/ignore scroll events. Motivated by
+ * https://github.com/facebook/docusaurus/pull/5618
+ */
+export function useScrollController(): ScrollController {
+  const context = useContext(ScrollMonitorContext)
+  if (context == null) {
+    throw new Error(
+      `useScrollController must be used by elements in ScrollControllerProvider`
+    )
+  }
+  return context
+}
+
+type ScrollPosition = { scrollX: number; scrollY: number }
+
+const getScrollPosition = (): ScrollPosition | null => ({
+  scrollX: window.pageXOffset,
+  scrollY: window.pageYOffset,
+})
+
+/**
+ * This hook fires an effect when the scroll position changes. The effect will
+ * be provided with the before/after scroll positions. Note that the effect may
+ * not be always run: if scrolling is disabled through `useScrollController`, it
+ * will be a no-op.
+ *
+ * @see {@link useScrollController}
+ */
+export function useScrollPosition(
+  effect: (
+    position: ScrollPosition,
+    lastPosition: ScrollPosition | null
+  ) => void,
+  deps: unknown[] = []
+): void {
+  const { scrollEventsEnabledRef } = useScrollController()
+  const lastPositionRef = useRef<ScrollPosition | null>(getScrollPosition())
+
+  const dynamicEffect = useEvent(effect)
+
+  useEffect(() => {
+    const handleScroll = () => {
+      if (!scrollEventsEnabledRef.current) {
+        return
+      }
+      const currentPosition = getScrollPosition()!
+      dynamicEffect(currentPosition, lastPositionRef.current)
+      lastPositionRef.current = currentPosition
+    }
+
+    const opts: AddEventListenerOptions & EventListenerOptions = {
+      passive: true,
+    }
+
+    handleScroll()
+    window.addEventListener("scroll", handleScroll, opts)
+
+    return () => window.removeEventListener("scroll", handleScroll, opts)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [dynamicEffect, scrollEventsEnabledRef, ...deps])
+}
+
+type UseScrollPositionSaver = {
+  /** Measure the top of an element, and store the details. */
+  save: (elem: HTMLElement) => void
+  /**
+   * Restore the page position to keep the stored element's position from
+   * the top of the viewport, and remove the stored details.
+   */
+  restore: () => { restored: boolean }
+}
+
+function useScrollPositionSaver(): UseScrollPositionSaver {
+  const lastElementRef = useRef<{ elem: HTMLElement | null; top: number }>({
+    elem: null,
+    top: 0,
+  })
+
+  const save = useCallback((elem: HTMLElement) => {
+    lastElementRef.current = {
+      elem,
+      top: elem.getBoundingClientRect().top,
+    }
+  }, [])
+
+  const restore = useCallback(() => {
+    const {
+      current: { elem, top },
+    } = lastElementRef
+    if (!elem) {
+      return { restored: false }
+    }
+    const newTop = elem.getBoundingClientRect().top
+    const heightDiff = newTop - top
+    if (heightDiff) {
+      window.scrollBy({ left: 0, top: heightDiff })
+    }
+    lastElementRef.current = { elem: null, top: 0 }
+
+    return { restored: heightDiff !== 0 }
+  }, [])
+
+  return useMemo(() => ({ save, restore }), [restore, save])
+}
+
+/**
+ * This hook permits to "block" the scroll position of a DOM element.
+ * The idea is that we should be able to update DOM content above this element
+ * but the screen position of this element should not change.
+ *
+ * Feature motivated by the Tabs groups: clicking on a tab may affect tabs of
+ * the same group upper in the tree, yet to avoid a bad UX, the clicked tab must
+ * remain under the user mouse.
+ *
+ * @see https://github.com/facebook/docusaurus/pull/5618
+ */
+export function useScrollPositionBlocker(): {
+  /**
+   * Takes an element, and keeps its screen position no matter what's getting
+   * rendered above it, until the next render.
+   */
+  blockElementScrollPositionUntilNextRender: (el: HTMLElement) => void
+} {
+  const scrollController = useScrollController()
+  const scrollPositionSaver = useScrollPositionSaver()
+
+  const nextLayoutEffectCallbackRef = useRef<(() => void) | undefined>(
+    undefined
+  )
+
+  const blockElementScrollPositionUntilNextRender = useCallback(
+    (el: HTMLElement) => {
+      scrollPositionSaver.save(el)
+      scrollController.disableScrollEvents()
+      nextLayoutEffectCallbackRef.current = () => {
+        const { restored } = scrollPositionSaver.restore()
+        nextLayoutEffectCallbackRef.current = undefined
+
+        // Restoring the former scroll position will trigger a scroll event. We
+        // need to wait for next scroll event to happen before enabling the
+        // scrollController events again.
+        if (restored) {
+          const handleScrollRestoreEvent = () => {
+            scrollController.enableScrollEvents()
+            window.removeEventListener("scroll", handleScrollRestoreEvent)
+          }
+          window.addEventListener("scroll", handleScrollRestoreEvent)
+        } else {
+          scrollController.enableScrollEvents()
+        }
+      }
+    },
+    [scrollController, scrollPositionSaver]
+  )
+
+  useLayoutEffect(() => {
+    // Queuing permits to restore scroll position after all useLayoutEffect
+    // have run, and yet preserve the sync nature of the scroll restoration
+    // See https://github.com/facebook/docusaurus/issues/8625
+    queueMicrotask(() => nextLayoutEffectCallbackRef.current?.())
+  })
+
+  return {
+    blockElementScrollPositionUntilNextRender,
+  }
+}
+
+type CancelScrollTop = () => void
+
+function smoothScrollNative(top: number): CancelScrollTop {
+  window.scrollTo({ top, behavior: "smooth" })
+  return () => {
+    // Nothing to cancel, it's natively cancelled if user tries to scroll down
+  }
+}
+
+function smoothScrollPolyfill(top: number): CancelScrollTop {
+  let raf: number | null = null
+  const isUpScroll = document.documentElement.scrollTop > top
+  function rafRecursion() {
+    const currentScroll = document.documentElement.scrollTop
+    if (
+      (isUpScroll && currentScroll > top) ||
+      (!isUpScroll && currentScroll < top)
+    ) {
+      raf = requestAnimationFrame(rafRecursion)
+      window.scrollTo(0, Math.floor((currentScroll - top) * 0.85) + top)
+    }
+  }
+  rafRecursion()
+
+  // Break the recursion. Prevents the user from "fighting" against that
+  // recursion producing a weird UX
+  return () => raf && cancelAnimationFrame(raf)
+}
+
+/**
+ * A "smart polyfill" of `window.scrollTo({ top, behavior: "smooth" })`.
+ * This currently always uses a polyfilled implementation unless
+ * `scroll-behavior: smooth` has been set in CSS, because native support
+ * detection for scroll behavior seems unreliable.
+ *
+ * This hook does not do anything by itself: it returns a start and a stop
+ * handle. You can execute either handle at any time.
+ */
+export function useSmoothScrollTo(): {
+  /**
+   * Start the scroll.
+   *
+   * @param top The final scroll top position.
+   */
+  startScroll: (top: number) => void
+  /**
+   * A cancel function, because the non-native smooth scroll-top
+   * implementation must be interrupted if user scrolls down. If there's no
+   * existing animation or the scroll is using native behavior, this is a no-op.
+   */
+  cancelScroll: CancelScrollTop
+} {
+  const cancelRef = useRef<CancelScrollTop | null>(null)
+  // Not all have support for smooth scrolling (particularly Safari mobile iOS)
+  // TODO proper detection is currently unreliable!
+  // see https://github.com/wessberg/scroll-behavior-polyfill/issues/16
+  // For now, we only use native scroll behavior if smooth is already set,
+  // because otherwise the polyfill produces a weird UX when both CSS and JS try
+  // to scroll a page, and they cancel each other.
+  const supportsNativeSmoothScrolling =
+    getComputedStyle(document.documentElement).scrollBehavior === "smooth"
+  return {
+    startScroll: (top: number) => {
+      cancelRef.current = supportsNativeSmoothScrolling
+        ? smoothScrollNative(top)
+        : smoothScrollPolyfill(top)
+    },
+    cancelScroll: () => cancelRef.current?.(),
+  }
+}

www/api-reference/hooks/use-client.ts

@@ -1,13 +0,0 @@
-import { useEffect, useState } from "react"
-
-const useClient = () => {
-  const [isClient, setIsClient] = useState(false)
-
-  useEffect(() => {
-    setIsClient(true)
-  }, [])
-
-  return isClient
-}
-
-export default useClient

www/api-reference/hooks/use-height-observer.ts

@@ -1,23 +0,0 @@
-"use client"
-
-import { useEffect } from "react"
-
-const useHeightObserver = () => {
-  useEffect(() => {
-    const storedHeight = window.localStorage.getItem("height")
-    if (storedHeight) {
-      document.body.style.height = storedHeight
-    }
-
-    const resizeObserver = new ResizeObserver((entries) => {
-      window.localStorage.setItem(
-        "height",
-        `${entries[0].target.clientHeight}px`
-      )
-    })
-
-    resizeObserver.observe(document.body)
-  }, [])
-}
-
-export default useHeightObserver

www/api-reference/hooks/use-tabs.ts

@@ -0,0 +1,92 @@
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react"
+
+export type BaseTabType = {
+  label: string
+  value: string
+}
+
+type EventData = {
+  storageValue: string
+}
+
+type TabProps<T> = {
+  tabs: T[]
+  group?: string
+}
+
+function useTabs<T extends BaseTabType>({ tabs, group }: TabProps<T>) {
+  const [selectedTab, setSelectedTab] = useState<T | null>(null)
+  const storageKey = useMemo(() => `tab_${group}`, [group])
+  const eventKey = useMemo(() => `tab_${group}_changed`, [group])
+  const scrollPosition = useRef<number>(0)
+
+  const changeSelectedTab = (tab: T) => {
+    scrollPosition.current = window.scrollY
+    setSelectedTab(tab)
+    localStorage.setItem(storageKey, tab.value)
+    window.dispatchEvent(
+      new CustomEvent<EventData>(eventKey, {
+        detail: {
+          storageValue: tab.value,
+        },
+      })
+    )
+  }
+
+  const findTabItem = useCallback(
+    (val: string) => {
+      const lowerVal = val.toLowerCase()
+      return tabs.find((t) => t.value.toLowerCase() === lowerVal)
+    },
+    [tabs]
+  )
+
+  const handleStorageChange = useCallback(
+    (e: CustomEvent<EventData>) => {
+      if (e.detail.storageValue !== selectedTab?.value) {
+        // check if tab exists
+        const tab = findTabItem(e.detail.storageValue)
+        if (tab) {
+          setSelectedTab(tab)
+        }
+      }
+    },
+    [selectedTab, findTabItem]
+  ) as EventListener
+
+  useEffect(() => {
+    if (!selectedTab) {
+      const storedSelectedTabValue = localStorage.getItem(storageKey)
+      setSelectedTab(
+        storedSelectedTabValue
+          ? findTabItem(storedSelectedTabValue) || tabs[0]
+          : tabs[0]
+      )
+    }
+  }, [selectedTab, storageKey, tabs, findTabItem])
+
+  useEffect(() => {
+    window.addEventListener(eventKey, handleStorageChange)
+
+    return () => {
+      window.removeEventListener(eventKey, handleStorageChange)
+    }
+  }, [handleStorageChange, eventKey])
+
+  useLayoutEffect(() => {
+    if (scrollPosition.current && window.scrollY !== scrollPosition.current) {
+      window.scrollTo(0, scrollPosition.current)
+    }
+  }, [selectedTab])
+
+  return { selectedTab, changeSelectedTab }
+}
+
+export default useTabs