@acmekit/docs-ui 2.13.41

package/src/hooks/use-scroll-utils/index.tsx

@@ -0,0 +1,372 @@
+
+/* 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,
+  useState,
+} from "react"
+import { getScrolledTop as getScrolledTopUtil, isElmWindow } from "../../utils"
+import { useKeyboardShortcut } from "../use-keyboard-shortcut"
+import { useLayout } from "../../providers/Layout"
+
+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>(undefined)
+
+  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
+  /** Retrieves the scrollable element. By default, it's window. */
+  scrollableElement: Element | Window | undefined
+  /** Retrieves the scroll top if the scrollable element */
+  getScrolledTop: () => number
+  /** Scrolls to an element */
+  scrollToElement: (elm: HTMLElement) => void
+  /** Scrolls to a top value */
+  scrollToTop: (top: number, parentTop?: number) => void
+}
+
+function useScrollControllerContextValue({
+  scrollableSelector,
+}: {
+  scrollableSelector: string
+  restoreScrollOnReload?: boolean
+}): ScrollController {
+  const scrollEventsEnabledRef = useRef(true)
+  const { showCollapsedNavbar } = useLayout()
+
+  const [scrollableElement, setScrollableElement] = useState<
+    Element | Window | undefined
+  >()
+
+  useEffect(() => {
+    setScrollableElement(
+      (document.querySelector(scrollableSelector) as Element) || window
+    )
+  }, [])
+
+  const getScrolledTop = () => {
+    return scrollableElement ? getScrolledTopUtil(scrollableElement) : 0
+  }
+
+  const scrollToElement = (elm: HTMLElement) => {
+    scrollToTop(elm.offsetTop)
+  }
+
+  const topMargin = useMemo(() => {
+    // might need a better way to set these static values
+    return showCollapsedNavbar ? 112 : 56
+  }, [showCollapsedNavbar])
+
+  const scrollToTop = (top: number, parentTop?: number) => {
+    const parentOffsetTop =
+      parentTop !== undefined
+        ? parentTop
+        : isElmWindow(scrollableElement)
+          ? 0
+          : scrollableElement instanceof HTMLElement
+            ? scrollableElement.offsetTop
+            : 0
+
+    scrollableElement?.scrollTo({
+      top: top - parentOffsetTop - topMargin,
+      behavior: "instant",
+    })
+  }
+
+  return useMemo(
+    () => ({
+      scrollEventsEnabledRef,
+      enableScrollEvents: () => {
+        scrollEventsEnabledRef.current = true
+      },
+      disableScrollEvents: () => {
+        scrollEventsEnabledRef.current = false
+      },
+      scrollableElement,
+      getScrolledTop,
+      scrollToElement,
+      scrollToTop,
+    }),
+    [scrollableElement]
+  )
+}
+
+const ScrollMonitorContext = React.createContext<ScrollController | undefined>(
+  undefined
+)
+
+export function ScrollControllerProvider({
+  children,
+  scrollableSelector = "",
+}: {
+  children: ReactNode
+  scrollableSelector?: string
+  restoreScrollOnReload?: boolean
+}) {
+  const value = useScrollControllerContextValue({
+    scrollableSelector,
+  })
+  useKeyboardShortcut({
+    metakey: false,
+    shortcutKeys: ["ArrowUp", "ArrowDown", "PageUp", "PageDown", "Home", "End"],
+    action: (e) => {
+      // check that document or body are focused
+      const activeElement = document.activeElement
+      if (
+        isElmWindow(value.scrollableElement) ||
+        !value.scrollableElement ||
+        (activeElement !== document.body &&
+          activeElement !== document.documentElement)
+      ) {
+        return
+      }
+
+      let newScroll = value.scrollableElement.scrollTop
+      const scrollThreshold = 50
+      const pageScrollAmount =
+        value.scrollableElement.clientHeight - scrollThreshold
+
+      switch (e.key) {
+        case "ArrowUp":
+          newScroll = -scrollThreshold
+          break
+        case "ArrowDown":
+          newScroll = scrollThreshold
+          break
+        case "PageUp":
+          newScroll = -pageScrollAmount
+          break
+        case "PageDown":
+          newScroll = pageScrollAmount
+          break
+        case "Home":
+          newScroll = -newScroll
+          break
+        case "End":
+          newScroll = value.scrollableElement.scrollHeight
+      }
+
+      value.scrollableElement?.scrollBy({
+        top: newScroll,
+        behavior: "smooth",
+      })
+    },
+  })
+  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)
+  }, [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 { scrollableElement } = useScrollController()
+  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) {
+      scrollableElement?.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,
+  }
+}

package/src/hooks/use-select/index.tsx

@@ -0,0 +1,99 @@
+import { useCallback, useMemo } from "react"
+
+export type OptionType = {
+  value: string
+  label: string
+  index?: string
+  isAllOption?: boolean
+  hitsPerPage?: number
+}
+
+export type SelectOptions = {
+  value: string | string[]
+  multiple?: boolean
+  options: OptionType[]
+  setSelected?: (value: string | string[]) => void
+  addSelected?: (value: string) => void
+  removeSelected?: (value: string) => void
+  handleAddAll?: (isAllSelected: boolean) => void
+}
+
+export const useSelect = ({
+  value,
+  options,
+  multiple = false,
+  setSelected,
+  addSelected,
+  removeSelected,
+  handleAddAll,
+}: SelectOptions) => {
+  const isValueSelected = useCallback(
+    (val: string) => {
+      return (
+        (typeof value === "string" && val === value) ||
+        (Array.isArray(value) && value.includes(val))
+      )
+    },
+    [value]
+  )
+
+  // checks if there are multiple selected values
+  const hasSelectedValues = useMemo(() => {
+    return multiple && Array.isArray(value) && value.length > 0
+  }, [value, multiple])
+
+  // checks if there are any selected values,
+  // whether multiple or one
+  const hasSelectedValue = useMemo(() => {
+    return hasSelectedValues || (typeof value === "string" && value.length)
+  }, [hasSelectedValues, value])
+
+  const selectedValues: OptionType[] = useMemo(() => {
+    if (typeof value === "string") {
+      const selectedValue = options.find((option) => option.value === value)
+      return selectedValue ? [selectedValue] : []
+    } else if (Array.isArray(value)) {
+      return options.filter((option) => value.includes(option.value))
+    }
+    return []
+  }, [options, value])
+
+  const isAllSelected = useMemo(() => {
+    return Array.isArray(value) && value.length === options.length
+  }, [options, value])
+
+  const handleChange = (selectedValue: string, wasSelected: boolean) => {
+    if (multiple) {
+      if (wasSelected) {
+        removeSelected?.(selectedValue)
+      } else {
+        addSelected?.(selectedValue)
+      }
+    } else {
+      setSelected?.(selectedValue)
+    }
+  }
+
+  const handleSelectAll = () => {
+    if (handleAddAll) {
+      handleAddAll(isAllSelected)
+    } else {
+      setSelected?.(options.map((option) => option.value))
+    }
+  }
+
+  const setSelectedValues = (values: string[]) => {
+    setSelected?.(values)
+  }
+
+  return {
+    isValueSelected,
+    hasSelectedValue,
+    hasSelectedValues,
+    selectedValues,
+    isAllSelected,
+    handleChange,
+    handleSelectAll,
+    setSelectedValues,
+  }
+}

package/src/hooks/use-tabs/index.tsx

@@ -0,0 +1,94 @@
+
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react"
+
+export type BaseTabType = {
+  label: string
+  value: string
+}
+
+export type EventData = {
+  storageValue: string
+}
+
+export type TabProps<T> = {
+  tabs: T[]
+  group?: string
+}
+
+export 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) => {
+    if (tab.value === selectedTab?.value) {
+      return
+    }
+    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 }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./constants"
+export * from "./global-config"
+
+export * from "./components"
+export * from "./hooks"
+export * from "./layouts"
+export * from "./providers"
+export * from "./utils"

package/src/layouts/barebone.tsx

@@ -0,0 +1,18 @@
+import clsx from "clsx"
+import React from "react"
+
+export type BareboneLayoutProps = {
+  htmlClassName?: string
+  children: React.ReactNode
+}
+
+export const BareboneLayout = ({
+  htmlClassName,
+  children,
+}: BareboneLayoutProps) => {
+  return (
+    <div className={clsx("h-full w-full", htmlClassName)}>
+      {children}
+    </div>
+  )
+}

package/src/layouts/index.ts

@@ -0,0 +1,4 @@
+export * from "./barebone"
+export * from "./root"
+export * from "./tight"
+export * from "./wide"

package/src/layouts/main-content.tsx

@@ -0,0 +1,86 @@
+
+import React, { useEffect } from "react"
+import clsx from "clsx"
+import {
+  MainNav,
+  useAiAssistant,
+  useIsBrowser,
+  useLayout,
+  useSidebar,
+  useSiteConfig,
+} from ".."
+import { ContentMenu } from "../components/ContentMenu"
+
+export type MainContentLayoutProps = {
+  mainWrapperClasses?: string
+  contentClassName?: string
+  children: React.ReactNode
+  showContentMenu?: boolean
+}
+
+export const MainContentLayout = ({
+  children,
+  mainWrapperClasses,
+  contentClassName,
+  showContentMenu = true,
+}: MainContentLayoutProps) => {
+  const { isBrowser } = useIsBrowser()
+  const { desktopSidebarOpen } = useSidebar()
+  const { mainContentRef, showCollapsedNavbar } = useLayout()
+  const { frontmatter } = useSiteConfig()
+  const { chatOpened } = useAiAssistant()
+
+  useEffect(() => {
+    if (!isBrowser) {
+      return
+    }
+    const rootLayout = document.getElementById("root-layout")
+    if (desktopSidebarOpen) {
+      rootLayout?.classList.add("lg:grid-cols-[221px_1fr]")
+    } else {
+      rootLayout?.classList.remove("lg:grid-cols-[221px_1fr]")
+    }
+  }, [desktopSidebarOpen, isBrowser])
+
+  return (
+    <div
+      className={clsx(
+        "relative max-w-full",
+        "h-full flex-1",
+        "flex flex-col",
+        "gap-docs_0.5 lg:py-docs_0.25 lg:mr-docs_0.25 scroll-m-docs_0.25",
+        !desktopSidebarOpen && "lg:ml-docs_0.25",
+        mainWrapperClasses
+      )}
+    >
+      <div
+        className={clsx(
+          "bg-acmekit-bg-base",
+          "flex-col items-center",
+          "h-full w-full",
+          "overflow-y-scroll overflow-x-hidden",
+          "md:rounded-docs_DEFAULT",
+          "shadow-elevation-card-rest dark:shadow-elevation-card-rest-dark",
+          mainWrapperClasses
+        )}
+        id="main"
+        ref={mainContentRef as React.RefObject<HTMLDivElement>}
+      >
+        <MainNav />
+        <div
+          className={clsx(
+            "pt-docs_4 lg:pt-docs_6 pb-docs_8 lg:pb-docs_4",
+            showContentMenu && "grid grid-cols-1 lg:mx-auto",
+            desktopSidebarOpen && "lg:grid-cols-[1fr_221px]",
+            chatOpened && showCollapsedNavbar && "pl-docs_1",
+            contentClassName
+          )}
+          id="content"
+        >
+          <div className="flex justify-center">{children}</div>
+        </div>
+        {showContentMenu && !frontmatter.hide_content_menu && <ContentMenu />}
+      </div>
+    </div>
+  )
+}