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
@@ -0,0 +1,4 @@
|
||||
export * from "./use-keyboard-shortcut"
|
||||
export * from "./use-scroll-utils"
|
||||
export * from "./use-select"
|
||||
export * from "./use-tabs"
|
||||
@@ -0,0 +1,72 @@
|
||||
"use client"
|
||||
|
||||
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 sidebarShortcut = 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", sidebarShortcut)
|
||||
|
||||
return () => {
|
||||
window.removeEventListener("keydown", sidebarShortcut)
|
||||
}
|
||||
}, [sidebarShortcut])
|
||||
}
|
||||
@@ -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?.(),
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,91 @@
|
||||
import { useCallback, useMemo } from "react"
|
||||
|
||||
export type OptionType = {
|
||||
value: string
|
||||
label: string
|
||||
index?: string
|
||||
isAllOption?: boolean
|
||||
}
|
||||
|
||||
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) {
|
||||
wasSelected
|
||||
? removeSelected?.(selectedValue)
|
||||
: addSelected?.(selectedValue)
|
||||
} else {
|
||||
setSelected?.(selectedValue)
|
||||
}
|
||||
}
|
||||
|
||||
const handleSelectAll = () => {
|
||||
if (handleAddAll) {
|
||||
handleAddAll(isAllSelected)
|
||||
} else {
|
||||
setSelected?.(options.map((option) => option.value))
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
isValueSelected,
|
||||
hasSelectedValue,
|
||||
hasSelectedValues,
|
||||
selectedValues,
|
||||
isAllSelected,
|
||||
handleChange,
|
||||
handleSelectAll,
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,92 @@
|
||||
"use client"
|
||||
|
||||
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) => {
|
||||
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 }
|
||||
}
|
||||
Reference in New Issue
Block a user