boltdocs 1.10.2 → 1.11.0

package/src/client/components/primitives/on-this-page.tsx

@@ -0,0 +1,461 @@
+import React, {
+  createContext,
+  use,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+  type RefObject,
+} from 'react'
+import scrollIntoView from 'scroll-into-view-if-needed'
+import { cn } from '../../utils/cn'
+import { useOnChange } from '../../utils/use-on-change'
+import type { ComponentBase, CompoundComponent } from './types'
+import { getItemId } from './helpers/observer'
+
+export interface TOCItemType {
+  title: ReactNode
+  url: string
+  depth: number
+  _step?: number
+}
+
+export type TableOfContents = TOCItemType[]
+
+export interface TOCItemInfo {
+  id: string
+  active: boolean
+  /** last time the item is updated */
+  t: number
+  /** currently active but not intersecting in viewport */
+  fallback: boolean
+  original?: TOCItemType
+}
+
+export interface AnchorProviderProps {
+  toc: TOCItemType[]
+  /**
+   * Only accept one active item at most
+   * @defaultValue false
+   */
+  single?: boolean
+  children?: ReactNode
+}
+
+export interface ScrollProviderProps {
+  /**
+   * Scroll into the view of container when active
+   */
+  containerRef: RefObject<HTMLElement | null>
+  children?: ReactNode
+}
+
+export interface OnThisPageContentProps extends ComponentBase {
+  ref?: React.Ref<HTMLDivElement>
+  scrollRef?: RefObject<HTMLElement | null>
+}
+
+export interface OnThisPageItemProps extends ComponentBase {
+  level?: number
+}
+
+export interface OnThisPageLinkProps extends ComponentBase {
+  href?: string
+  active?: boolean
+  onClick?: (event: React.MouseEvent<HTMLAnchorElement>) => void
+}
+
+export interface OnThisPageIndicatorProps extends ComponentBase {
+  style?: React.CSSProperties
+}
+
+const ItemsContext = createContext<TOCItemInfo[] | null>(null)
+const ScrollContext = createContext<RefObject<HTMLElement | null> | null>(null)
+
+class Observer {
+  items: TOCItemInfo[] = []
+  single = false
+  private observer: IntersectionObserver | null = null
+  onChange?: () => void
+
+  private callback(entries: IntersectionObserverEntry[]) {
+    if (entries.length === 0) return
+
+    let hasActive = false
+    this.items = this.items.map((item) => {
+      const entry = entries.find((entry) => entry.target.id === item.id)
+      let active = entry ? entry.isIntersecting : item.active && !item.fallback
+      if (this.single && hasActive) active = false
+
+      if (item.active !== active) {
+        item = {
+          ...item,
+          t: Date.now(),
+          active,
+          fallback: false,
+        }
+      }
+
+      if (active) hasActive = true
+      return item
+    })
+
+    if (!hasActive && entries[0].rootBounds) {
+      const viewTop = entries[0].rootBounds.top
+      let min = Number.MAX_VALUE
+      let fallbackIdx = -1
+
+      for (let i = 0; i < this.items.length; i++) {
+        const element = document.getElementById(this.items[i].id)
+        if (!element) continue
+
+        const d = Math.abs(viewTop - element.getBoundingClientRect().top)
+        if (d < min) {
+          fallbackIdx = i
+          min = d
+        }
+      }
+
+      if (fallbackIdx !== -1) {
+        this.items[fallbackIdx] = {
+          ...this.items[fallbackIdx],
+          active: true,
+          fallback: true,
+          t: Date.now(),
+        }
+      }
+    }
+
+    this.onChange?.()
+  }
+
+  setItems(newItems: TOCItemType[]) {
+    const observer = this.observer
+    if (observer) {
+      for (const item of this.items) {
+        const element = document.getElementById(item.id)
+        if (!element) continue
+        observer.unobserve(element)
+      }
+    }
+
+    this.items = []
+    for (const item of newItems) {
+      const id = getItemId(item.url)
+      if (!id) continue
+
+      this.items.push({
+        id,
+        active: false,
+        fallback: false,
+        t: 0,
+        original: item,
+      })
+    }
+    this.watchItems()
+
+    // In an SPA, the TOC might update before the MDX content is in the DOM.
+    // We perform a few delayed scans to ensure we catch those elements.
+    if (typeof window !== 'undefined') {
+      setTimeout(() => this.watchItems(), 100)
+      setTimeout(() => this.watchItems(), 500)
+      setTimeout(() => this.watchItems(), 1000)
+    }
+
+    this.onChange?.()
+  }
+
+  watch(options?: IntersectionObserverInit) {
+    if (this.observer) return
+    this.observer = new IntersectionObserver(this.callback.bind(this), options)
+    this.watchItems()
+  }
+
+  private watchItems() {
+    if (!this.observer) return
+    for (const item of this.items) {
+      const element = document.getElementById(item.id)
+      if (!element) continue
+      this.observer.observe(element)
+    }
+  }
+
+  unwatch() {
+    this.observer?.disconnect()
+    this.observer = null
+  }
+}
+
+export function useItems() {
+  const ctx = use(ItemsContext)
+  if (!ctx)
+    throw new Error(
+      `Component must be used under the <AnchorProvider /> component.`,
+    )
+  return ctx
+}
+
+export function useScrollStatus(ref: RefObject<HTMLElement | null>) {
+  const [status, setStatus] = useState({
+    isOverflowing: false,
+    isAtBottom: false,
+  })
+
+  useEffect(() => {
+    const el = ref.current
+    if (!el) return
+
+    const checkStatus = () => {
+      const isOverflowing = el.scrollHeight > el.clientHeight
+      // We use a 2px threshold for floating point math issues
+      const isAtBottom = el.scrollHeight - el.scrollTop <= el.clientHeight + 2
+      setStatus({ isOverflowing, isAtBottom })
+    }
+
+    checkStatus()
+    el.addEventListener('scroll', checkStatus, { passive: true })
+    window.addEventListener('resize', checkStatus)
+
+    const mutationObserver = new MutationObserver(checkStatus)
+    mutationObserver.observe(el, { childList: true, subtree: true })
+
+    return () => {
+      el.removeEventListener('scroll', checkStatus)
+      window.removeEventListener('resize', checkStatus)
+      mutationObserver.disconnect()
+    }
+  }, [ref])
+
+  return status
+}
+
+export function useActiveAnchor(): string | undefined {
+  const items = useItems()
+  return useMemo(() => {
+    let out: TOCItemInfo | undefined
+    for (const item of items) {
+      if (!item.active) continue
+      if (!out || item.t > out.t) {
+        out = item
+      }
+    }
+    return out?.id
+  }, [items])
+}
+
+export function useActiveAnchors(): string[] {
+  const items = useItems()
+  return useMemo(() => {
+    const out: string[] = []
+    for (const item of items) {
+      if (item.active) out.push(item.id)
+    }
+    return out
+  }, [items])
+}
+
+/** Optional: add auto-scroll to TOC items. */
+export function ScrollProvider({
+  containerRef,
+  children,
+}: ScrollProviderProps) {
+  return (
+    <ScrollContext.Provider value={containerRef}>
+      {children}
+    </ScrollContext.Provider>
+  )
+}
+
+export function AnchorProvider({
+  toc,
+  single = false,
+  children,
+}: AnchorProviderProps) {
+  const observer = useMemo(() => new Observer(), [])
+  const [items, setItems] = useState<TOCItemInfo[]>(observer.items)
+
+  observer.single = single
+  useEffect(() => {
+    observer.setItems(toc)
+  }, [observer, toc])
+
+  useEffect(() => {
+    observer.watch({
+      rootMargin: '0px',
+      threshold: 0.98,
+    })
+    observer.onChange = () => setItems([...observer.items])
+
+    return () => {
+      observer.unwatch()
+    }
+  }, [observer])
+
+  return <ItemsContext.Provider value={items}>{children}</ItemsContext.Provider>
+}
+
+export const OnThisPageRoot = ({ children, className }: ComponentBase) => {
+  return (
+    <nav
+      className={cn(
+        'sticky top-navbar hidden xl:flex flex-col shrink-0',
+        'w-toc',
+        'py-8 pl-6 pr-4',
+        className,
+      )}
+    >
+      {children}
+    </nav>
+  )
+}
+
+export const OnThisPageHeader = ({
+  children,
+  className,
+  ...props
+}: ComponentBase) => {
+  return (
+    <div
+      className={cn(
+        'mb-4 text-xs font-bold uppercase tracking-wider text-text-main',
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </div>
+  )
+}
+
+export const OnThisPageContent = ({
+  children,
+  className,
+  ref,
+  ...props
+}: OnThisPageContentProps) => {
+  const internalRef = useRef<HTMLDivElement>(null)
+
+  useImperativeHandle(ref, () => internalRef.current!)
+
+  const { isOverflowing, isAtBottom } = useScrollStatus(internalRef)
+
+  return (
+    <div
+      ref={internalRef}
+      className={cn(
+        'relative overflow-y-auto boltdocs-otp-content',
+        isOverflowing &&
+          !isAtBottom &&
+          'mask-[linear-gradient(to_bottom,black_85%,transparent_100%)]',
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </div>
+  )
+}
+
+OnThisPageContent.displayName = 'OnThisPageContent'
+
+export const OnThisPageList = ({ children, className }: ComponentBase) => {
+  return (
+    <ul
+      className={cn(
+        'relative space-y-1 text-sm border-l border-border-subtle',
+        className,
+      )}
+    >
+      {children}
+    </ul>
+  )
+}
+
+export const OnThisPageItem = ({
+  level,
+  children,
+  className,
+}: OnThisPageItemProps) => {
+  return <li className={cn(level === 3 && 'pl-3', className)}>{children}</li>
+}
+
+export const OnThisPageLink = ({
+  children,
+  href,
+  active,
+  onClick,
+  className,
+}: OnThisPageLinkProps) => {
+  const items = use(ItemsContext)
+  const containerRef = use(ScrollContext)
+  const id = href ? getItemId(href) : null
+  const anchorRef = useRef<HTMLAnchorElement>(null)
+  const [internalActive, setInternalActive] = useState(active)
+
+  useOnChange(
+    id && items ? items.find((i) => i.id === id)?.active : null,
+    (newActive) => {
+      if (newActive !== null && newActive !== internalActive) {
+        setInternalActive(!!newActive)
+
+        if (newActive && anchorRef.current && containerRef?.current) {
+          scrollIntoView(anchorRef.current, {
+            behavior: 'smooth',
+            block: 'center',
+            inline: 'center',
+            scrollMode: 'if-needed',
+            boundary: containerRef.current,
+          })
+        }
+      }
+    },
+  )
+
+  // Also sync with external active prop if provided
+  useEffect(() => {
+    if (active !== undefined) setInternalActive(active)
+  }, [active])
+
+  return (
+    <a
+      ref={anchorRef}
+      href={href}
+      onClick={onClick}
+      data-active={internalActive}
+      className={cn(
+        'block py-1 pl-4 text-[13px] outline-none transition-colors hover:text-text-main',
+        internalActive ? 'text-primary-500 font-medium' : 'text-text-muted',
+        className,
+      )}
+    >
+      {children}
+    </a>
+  )
+}
+
+export const OnThisPageIndicator = ({
+  style,
+  className,
+}: OnThisPageIndicatorProps) => {
+  return (
+    <div
+      className={cn(
+        'absolute -left-px w-0.5 rounded-full bg-primary-500 transition-all duration-300',
+        className,
+      )}
+      style={style}
+    />
+  )
+}
+
+export default {
+  OnThisPageRoot,
+  OnThisPageHeader,
+  OnThisPageContent,
+  OnThisPageList,
+  OnThisPageItem,
+  OnThisPageLink,
+  OnThisPageIndicator,
+}

package/src/client/components/primitives/page-nav.tsx

@@ -0,0 +1,87 @@
+import * as RAC from 'react-aria-components'
+import { ChevronLeft, ChevronRight } from 'lucide-react'
+import { cn } from '@client/utils/cn'
+import type { ComponentBase } from './types'
+
+export interface PageNavProps extends ComponentBase {
+  to: string
+  direction: 'prev' | 'next'
+}
+
+export const PageNavRoot = ({ children, className }: ComponentBase) => {
+  return (
+    <nav
+      className={cn(
+        'grid grid-cols-1 sm:grid-cols-2 gap-4 mt-12 pt-8 border-t border-border-subtle',
+        className,
+      )}
+    >
+      {children}
+    </nav>
+  )
+}
+
+export const PageNavLink = ({
+  children,
+  to,
+  direction,
+  className,
+}: PageNavProps) => {
+  const isNext = direction === 'next'
+  return (
+    <RAC.Link
+      href={to}
+      className={cn(
+        'flex group items-center p-4 rounded-xl border border-border-subtle bg-bg-surface outline-none',
+        'transition-all hover:bg-bg-main hover:border-primary-500 hover:shadow-lg',
+        'focus-visible:ring-2 focus-visible:ring-primary-500/30',
+        isNext ? 'text-right justify-end' : 'text-left justify-start',
+        className,
+      )}
+    >
+      {!isNext && (
+        <ChevronLeft className="mr-3 h-5 w-5 text-text-muted group-hover:text-primary-500 transition-transform group-hover:-translate-x-1" />
+      )}
+      <div className="flex flex-col gap-1 flex-1">{children}</div>
+      {isNext && (
+        <ChevronRight className="ml-3 h-5 w-5 text-text-muted group-hover:text-primary-500 transition-transform group-hover:translate-x-1" />
+      )}
+    </RAC.Link>
+  )
+}
+
+export const PageNavTitle = ({ children, className }: ComponentBase) => {
+  return (
+    <span
+      className={cn(
+        'text-xs font-medium uppercase tracking-wider text-text-muted',
+        className,
+      )}
+    >
+      {children}
+    </span>
+  )
+}
+
+export const PageNavDescription = ({ children, className }: ComponentBase) => {
+  return (
+    <span
+      className={cn('text-base font-bold text-text-main truncate', className)}
+    >
+      {children}
+    </span>
+  )
+}
+
+export const PageNavIcon = ({ children }: ComponentBase) => {
+  return <>{children}</>
+}
+
+export default {
+  PageNavRoot,
+  PageNavLink: Object.assign(PageNavLink, {
+    Title: PageNavTitle,
+    Description: PageNavDescription,
+    Icon: PageNavIcon,
+  }),
+}

package/src/client/components/primitives/popover.tsx

@@ -0,0 +1,47 @@
+'use client'
+
+import * as RAC from 'react-aria-components'
+import { cn } from '@client/utils/cn'
+
+export interface PopoverProps extends Omit<RAC.PopoverProps, 'children'> {
+  children: React.ReactNode
+  className?: string
+  showArrow?: boolean
+}
+
+/**
+ * A reusable Popover primitive with premium glassmorphism styling and smooth animations.
+ */
+export const Popover = ({
+  children,
+  className,
+  showArrow,
+  ...props
+}: PopoverProps) => {
+  return (
+    <RAC.Popover
+      offset={8}
+      {...props}
+      className={RAC.composeRenderProps(className, (className) =>
+        cn(
+          'z-50 overflow-auto rounded-xl border border-border-subtle bg-bg-surface/80 shadow-xl backdrop-blur-md outline-none',
+          'entering:animate-in entering:fade-in entering:zoom-in-95 exiting:animate-out exiting:fade-out exiting:zoom-out-95 fill-mode-forwards',
+          className,
+        ),
+      )}
+    >
+      {showArrow && (
+        <RAC.OverlayArrow className="group">
+          <svg
+            viewBox="0 0 12 12"
+            className="block h-3 w-3 fill-bg-surface/80 stroke-border-subtle group-placement-bottom:rotate-180 group-placement-left:-rotate-90 group-placement-right:rotate-90"
+            aria-hidden="true"
+          >
+            <path d="M0 0 L6 6 L12 0" />
+          </svg>
+        </RAC.OverlayArrow>
+      )}
+      {children as any}
+    </RAC.Popover>
+  )
+}