@acmekit/docs-ui 2.13.41

package/src/hooks/use-click-outside/index.tsx

@@ -0,0 +1,37 @@
+
+import React, { useCallback, useEffect } from "react"
+import { useIsBrowser } from "../../providers/BrowserProvider"
+
+export type UseClickOutsideProps = {
+  elmRef: React.RefObject<HTMLElement | null>
+  onClickOutside: (e: MouseEvent) => void
+}
+
+export const useClickOutside = ({
+  elmRef,
+  onClickOutside,
+}: UseClickOutsideProps) => {
+  const { isBrowser } = useIsBrowser()
+
+  const checkClickOutside = useCallback(
+    (e: MouseEvent) => {
+      const node = e.target as Node
+      if (!elmRef.current?.contains(node) && node.isConnected) {
+        onClickOutside(e)
+      }
+    },
+    [elmRef.current, onClickOutside]
+  )
+
+  useEffect(() => {
+    if (!isBrowser) {
+      return
+    }
+
+    window.document.addEventListener("click", checkClickOutside)
+
+    return () => {
+      window.document.removeEventListener("click", checkClickOutside)
+    }
+  }, [isBrowser, checkClickOutside])
+}

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

@@ -0,0 +1,128 @@
+
+import React, { useState } from "react"
+// @ts-expect-error can't install the types package because it doesn't support React v19
+import { CSSTransition } from "react-transition-group"
+
+export type CollapsibleProps = {
+  initialValue?: boolean
+  heightAnimation?: boolean
+  translateEnabled?: boolean
+  onClose?: () => void
+  unmountOnExit?: boolean
+  childrenRef?: React.RefObject<HTMLElement | null>
+  useChild?: boolean
+}
+
+export type CollapsibleReturn = {
+  getCollapsibleElms: (children: React.ReactNode) => React.JSX.Element
+  collapsed: boolean
+  setCollapsed: React.Dispatch<React.SetStateAction<boolean>>
+}
+
+export const useCollapsible = ({
+  initialValue = true,
+  heightAnimation = false,
+  translateEnabled = true,
+  onClose,
+  unmountOnExit = true,
+  childrenRef,
+  useChild = true,
+}: CollapsibleProps): CollapsibleReturn => {
+  const [collapsed, setCollapsed] = useState(initialValue)
+
+  const getNodeFromChildrenRef = () => {
+    if (!useChild) {
+      return childrenRef?.current
+    }
+
+    return (
+      (childrenRef?.current?.firstElementChild as HTMLElement) ||
+      childrenRef?.current
+    )
+  }
+
+  const getCollapsibleElms = (children: React.ReactNode) => {
+    return (
+      <CSSTransition
+        unmountOnExit={unmountOnExit}
+        in={!collapsed}
+        timeout={150}
+        nodeRef={childrenRef}
+        onEnter={() => {
+          const node = getNodeFromChildrenRef()
+          if (!node) {
+            return
+          }
+
+          if (heightAnimation) {
+            node.classList.add("transition-[height]")
+            node.style.height = `0px`
+          } else {
+            node.classList.add("!mb-docs_2", "!mt-0")
+            if (translateEnabled) {
+              node.classList.add("translate-y-docs_1", "transition-transform")
+            }
+          }
+        }}
+        onEntering={() => {
+          const node = getNodeFromChildrenRef()
+          if (!node) {
+            return
+          }
+
+          if (heightAnimation) {
+            node.style.height = `${node.scrollHeight}px`
+          }
+        }}
+        onEntered={() => {
+          const node = getNodeFromChildrenRef()
+          if (!node) {
+            return
+          }
+
+          if (heightAnimation) {
+            node.style.height = `auto`
+          }
+        }}
+        onExit={() => {
+          const node = getNodeFromChildrenRef()
+          if (!node) {
+            return
+          }
+
+          if (heightAnimation) {
+            node.style.height = `${node.scrollHeight}px`
+          } else {
+            if (translateEnabled) {
+              node.classList.add("transition-transform", "!-translate-y-docs_1")
+            }
+            setTimeout(() => {
+              onClose?.()
+            }, 100)
+          }
+        }}
+        onExiting={() => {
+          const node = getNodeFromChildrenRef()
+          if (!node) {
+            return
+          }
+
+          if (heightAnimation) {
+            node.style.height = `0px`
+            setTimeout(() => {
+              onClose?.()
+            }, 100)
+          }
+        }}
+      >
+        {children}
+      </CSSTransition>
+    )
+  }
+
+  return {
+    getCollapsibleElms,
+    collapsed,
+    setCollapsed,
+  }
+}

package/src/hooks/use-collapsible-code-lines/index.tsx

@@ -0,0 +1,149 @@
+
+import {
+  LineInputProps,
+  LineOutputProps,
+  Token,
+  TokenInputProps,
+  TokenOutputProps,
+} from "prism-react-renderer"
+import React, { useCallback, useMemo, useRef } from "react"
+import { CodeBlockCollapsibleLines } from "../../components/CodeBlock/Collapsible/Lines"
+import { useCollapsible } from "../use-collapsible"
+
+export type HighlightProps = {
+  getLineProps: (input: LineInputProps) => LineOutputProps
+  getTokenProps: (input: TokenInputProps) => TokenOutputProps
+}
+
+export type CollapsibleCodeLines = {
+  collapsibleLinesStr?: string
+  getLines: (
+    token: Token[][],
+    highlightProps: HighlightProps,
+    lineNumberOffset?: number
+  ) => React.JSX.Element[]
+}
+
+export type CollapsedCodeLinesPosition = "start" | "end"
+
+export const useCollapsibleCodeLines = ({
+  collapsibleLinesStr,
+  getLines,
+}: CollapsibleCodeLines) => {
+  const collapsedRange:
+    | {
+        start: number
+        end: number | undefined
+      }
+    | undefined = useMemo(() => {
+    if (!collapsibleLinesStr) {
+      return
+    }
+
+    const splitCollapsedLines = collapsibleLinesStr
+      .split("-")
+      .map((lineNumber) => parseInt(lineNumber))
+
+    if (
+      !splitCollapsedLines.length ||
+      (splitCollapsedLines.length >= 2 &&
+        splitCollapsedLines[0] !== 1 &&
+        splitCollapsedLines[1] < 2)
+    ) {
+      return
+    }
+
+    return {
+      start: splitCollapsedLines[0],
+      end: splitCollapsedLines[1],
+    }
+  }, [collapsibleLinesStr])
+
+  const isCollapsible = useCallback(
+    (tokens: Token[][]) => {
+      return collapsedRange && collapsedRange.start < tokens.length
+    },
+    [collapsedRange]
+  )
+
+  const type: CollapsedCodeLinesPosition | undefined = useMemo(() => {
+    if (!collapsedRange) {
+      return undefined
+    }
+    return collapsedRange.start === 1 ? "start" : "end"
+  }, [collapsedRange])
+
+  const ref = useRef(null)
+  const collapsibleHookResult = useCollapsible({
+    unmountOnExit: false,
+    translateEnabled: false,
+    heightAnimation: true,
+    childrenRef: ref,
+  })
+
+  const getCollapsedLinesElm = useCallback(
+    ({
+      tokens,
+      highlightProps,
+    }: {
+      tokens: Token[][]
+      highlightProps: HighlightProps
+    }) => {
+      if (!collapsedRange || !type || !isCollapsible(tokens)) {
+        return <></>
+      }
+
+      const startIndex =
+        type === "start" ? collapsedRange.start - 1 : collapsedRange.start
+
+      const lines = tokens.slice(
+        startIndex,
+        collapsedRange.end
+          ? Math.min(collapsedRange.end, tokens.length)
+          : tokens.length
+      )
+
+      return (
+        <CodeBlockCollapsibleLines {...collapsibleHookResult} type={type}>
+          {getLines(lines, highlightProps, startIndex)}
+        </CodeBlockCollapsibleLines>
+      )
+    },
+    [collapsedRange, collapsibleHookResult, isCollapsible, type]
+  )
+
+  const getNonCollapsedLinesElm = useCallback(
+    ({
+      tokens,
+      highlightProps,
+    }: {
+      tokens: Token[][]
+      highlightProps: HighlightProps
+    }) => {
+      if (!collapsedRange || !isCollapsible(tokens)) {
+        return getLines(tokens, highlightProps)
+      }
+
+      const isCollapseBeginning = collapsedRange.start === 1
+      const lines = tokens.slice(
+        isCollapseBeginning ? collapsedRange.end || tokens.length : 0,
+        isCollapseBeginning ? undefined : collapsedRange.start
+      )
+
+      return getLines(
+        lines,
+        highlightProps,
+        isCollapseBeginning ? collapsedRange.end : 0
+      )
+    },
+    [collapsedRange, collapsibleHookResult, isCollapsible]
+  )
+
+  return {
+    getCollapsedLinesElm,
+    getNonCollapsedLinesElm,
+    type,
+    isCollapsible,
+    ...collapsibleHookResult,
+  }
+}

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

@@ -0,0 +1,28 @@
+
+import { useCallback, useEffect, useRef, useState } from "react"
+
+type useCopyReturnType = {
+  isCopied: boolean
+  handleCopy: () => void
+}
+
+export const useCopy = (text: string): useCopyReturnType => {
+  const [isCopied, setIsCopied] = useState(false)
+  const copyTimeout = useRef<number>(0)
+
+  const handleCopy = useCallback(() => {
+    navigator.clipboard
+      .writeText(text.trim())
+      .then(() => {
+        setIsCopied(true)
+        copyTimeout.current = window.setTimeout(() => {
+          setIsCopied(false)
+        }, 1000)
+      })
+      .catch(console.error)
+  }, [text])
+
+  useEffect(() => () => window.clearTimeout(copyTimeout.current), [])
+
+  return { isCopied, handleCopy }
+}

package/src/hooks/use-heading-url/index.tsx

@@ -0,0 +1,32 @@
+
+import { useLocation } from "react-router-dom"
+import { useIsBrowser } from "../../providers/BrowserProvider"
+import { useSiteConfig } from "../../providers/SiteConfig"
+import { useMemo } from "react"
+
+type useHeadingUrlProps = {
+  id: string
+}
+
+export const useHeadingUrl = ({ id }: useHeadingUrlProps) => {
+  const { isBrowser } = useIsBrowser()
+  const {
+    config: { basePath },
+  } = useSiteConfig()
+  const { pathname } = useLocation()
+  const headingUrl = useMemo(() => {
+    const hash = `#${id}`
+    if (!isBrowser) {
+      return hash
+    }
+
+    const url = `${window.location.origin}${basePath}${pathname}`.replace(
+      /\/$/,
+      ""
+    )
+
+    return `${url}${hash}`
+  }, [id, isBrowser, pathname])
+
+  return headingUrl
+}

package/src/hooks/use-is-external-link/index.tsx

@@ -0,0 +1,19 @@
+import { useMemo } from "react"
+
+type UseIsExternalLinkProps = {
+  href?: string
+}
+
+export const useIsExternalLink = ({ href }: UseIsExternalLinkProps) => {
+  const isExternal = useMemo(() => {
+    return (
+      href &&
+      !href.startsWith("/") &&
+      !href.startsWith("https://docs.acmekit.com") &&
+      !href.startsWith("http://localhost:") &&
+      !href.startsWith("#")
+    )
+  }, [href])
+
+  return isExternal
+}

package/src/hooks/use-keyboard-shortcut/index.tsx

@@ -0,0 +1,71 @@
+
+import { useCallback, useEffect } from "react"
+
+export type useKeyboardShortcutOptions = {
+  metakey?: boolean
+  shortcutKeys: string[]
+  action: (e: KeyboardEvent) => void
+  checkEditing?: boolean
+  preventDefault?: boolean
+  isLoading?: boolean
+}
+
+export const useKeyboardShortcut = ({
+  metakey = true,
+  shortcutKeys,
+  action,
+  checkEditing = true,
+  preventDefault = true,
+  isLoading = false,
+}: useKeyboardShortcutOptions) => {
+  function isEditingContent(event: KeyboardEvent) {
+    const element = event.target as HTMLElement
+    const tagName = element.tagName
+    return (
+      element.isContentEditable ||
+      tagName === "INPUT" ||
+      tagName === "SELECT" ||
+      tagName === "TEXTAREA"
+    )
+  }
+
+  const checkKeysPressed = useCallback(
+    (pressedKey: string) => {
+      const lowerPressedKey = pressedKey.toLowerCase()
+      return shortcutKeys.some(
+        (value) => lowerPressedKey === value.toLowerCase()
+      )
+    },
+    [shortcutKeys]
+  )
+
+  const onKeyDown = useCallback(
+    (e: KeyboardEvent) => {
+      // the event is triggered when an input
+      // autocompletes, and in that case
+      // e.key will be empty
+      if (isLoading || !e.key) {
+        return
+      }
+      if (
+        (!metakey || e.metaKey || e.ctrlKey) &&
+        checkKeysPressed(e.key) &&
+        (!checkEditing || !isEditingContent(e))
+      ) {
+        if (preventDefault) {
+          e.preventDefault()
+        }
+        action(e)
+      }
+    },
+    [isLoading, metakey, checkKeysPressed, checkEditing, action, preventDefault]
+  )
+
+  useEffect(() => {
+    window.addEventListener("keydown", onKeyDown)
+
+    return () => {
+      window.removeEventListener("keydown", onKeyDown)
+    }
+  }, [onKeyDown])
+}

package/src/hooks/use-mutation-observer/index.ts

@@ -0,0 +1,32 @@
+
+import { useEffect } from "react"
+
+type UseMutationObserverProps = {
+  elm: Document | HTMLElement | undefined
+  callback: () => void
+  options?: {
+    attributes?: boolean
+    characterData?: boolean
+    childList?: boolean
+    subtree?: boolean
+  }
+}
+
+export const useMutationObserver = ({
+  elm,
+  callback,
+  options = {
+    attributes: true,
+    characterData: true,
+    childList: true,
+    subtree: true,
+  },
+}: UseMutationObserverProps) => {
+  useEffect(() => {
+    if (elm) {
+      const observer = new MutationObserver(callback)
+      observer.observe(elm, options)
+      return () => observer.disconnect()
+    }
+  }, [callback, options])
+}

package/src/hooks/use-page-scroll-manager/index.tsx

@@ -0,0 +1,82 @@
+
+import { useLocation } from "react-router-dom"
+import { useScrollController } from "../use-scroll-utils"
+import { useEffect, useState } from "react"
+import { getScrolledTop, isElmWindow } from "../../utils"
+
+export const usePageScrollManager = () => {
+  const { pathname } = useLocation()
+  const { scrollableElement } = useScrollController()
+  const [checkedPageReload, setCheckedPageReload] = useState(false)
+
+  const isPageReloaded = () =>
+    (window.performance.navigation &&
+      window.performance.navigation.type === 1) ||
+    window.performance
+      .getEntriesByType("navigation")
+      .map((nav) => (nav as PerformanceNavigationTiming).type)
+      .includes("reload")
+
+  const tryToScroll = () => {
+    if (getScrolledTop(scrollableElement) !== 0 && !location.hash) {
+      scrollableElement?.scrollTo({
+        top: 0,
+      })
+    } else if (location.hash) {
+      // retrieve and scroll to element
+      const targetElm =
+        scrollableElement && typeof document !== "undefined"
+          ? document.getElementById(location.hash.replace("#", ""))
+          : undefined
+
+      scrollableElement?.scrollTo({
+        top: targetElm ? targetElm.offsetTop : 0,
+      })
+    }
+  }
+
+  useEffect(() => {
+    if (checkedPageReload) {
+      setCheckedPageReload(false)
+    }
+  }, [pathname])
+
+  useEffect(() => {
+    if (!scrollableElement || checkedPageReload) {
+      return
+    }
+
+    if (isPageReloaded()) {
+      const loadedScrollPosition = localStorage.getItem("scrollPos")
+      if (loadedScrollPosition) {
+        scrollableElement?.scrollTo({
+          top: parseInt(loadedScrollPosition),
+        })
+        localStorage.removeItem("scrollPos")
+      } else {
+        tryToScroll()
+      }
+    } else {
+      tryToScroll()
+    }
+
+    setCheckedPageReload(true)
+
+    window.addEventListener("beforeunload", () => {
+      const scrollPos = isElmWindow(scrollableElement)
+        ? scrollableElement.screenY
+        : scrollableElement?.scrollTop
+
+      if (scrollPos) {
+        localStorage.setItem(
+          "scrollPos",
+          `${
+            isElmWindow(scrollableElement)
+              ? scrollableElement.screenY
+              : scrollableElement?.scrollTop
+          }`
+        )
+      }
+    })
+  }, [scrollableElement, checkedPageReload])
+}

package/src/hooks/use-resize-observer/index.ts

@@ -0,0 +1,20 @@
+import { useEffect } from "react"
+
+export function useResizeObserver(
+  ref: React.RefObject<HTMLElement | null>,
+  callback: (entry: ResizeObserverEntry) => void
+) {
+  useEffect(() => {
+    const el = ref.current
+    if (!el) return
+
+    const observer = new ResizeObserver((entries) => {
+      if (entries[0]) {
+        callback(entries[0])
+      }
+    })
+
+    observer.observe(el)
+    return () => observer.disconnect()
+  }, [ref, callback])
+}