docs: create docs workspace (#5174)
* docs: migrate ui docs to docs universe * created yarn workspace * added eslint and tsconfig configurations * fix eslint configurations * fixed eslint configurations * shared tailwind configurations * added shared ui package * added more shared components * migrating more components * made details components shared * move InlineCode component * moved InputText * moved Loading component * Moved Modal component * moved Select components * Moved Tooltip component * moved Search components * moved ColorMode provider * Moved Notification components and providers * used icons package * use UI colors in api-reference * moved Navbar component * used Navbar and Search in UI docs * added Feedback to UI docs * general enhancements * fix color mode * added copy colors file from ui-preset * added features and enhancements to UI docs * move Sidebar component and provider * general fixes and preparations for deployment * update docusaurus version * adjusted versions * fix output directory * remove rootDirectory property * fix yarn.lock * moved code component * added vale for all docs MD and MDX * fix tests * fix vale error * fix deployment errors * change ignore commands * add output directory * fix docs test * general fixes * content fixes * fix announcement script * added changeset * fix vale checks * added nofilter option * fix vale error
This commit is contained in:
Shahed Nasser
GitHub
331
www/packages/docs-ui/src/hooks/use-scroll-utils/index.tsx
Normal file
331
www/packages/docs-ui/src/hooks/use-scroll-utils/index.tsx
Normal file
@@ -0,0 +1,331 @@
|
||||
"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)
|
||||
}, [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?.(),
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user