boltdocs 2.6.2 → 2.7.0

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

@@ -11,7 +11,6 @@ import {
 } 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 } from './types'
 import { getItemId, Observer } from './helpers/observer'
 
@@ -41,6 +40,10 @@ export interface AnchorProviderProps {
    * @defaultValue false
    */
   single?: boolean
+  /**
+   * Custom IntersectionObserver options
+   */
+  observerOptions?: IntersectionObserverInit
   children?: ReactNode
 }
 
@@ -123,6 +126,7 @@ export function ScrollProvider({
 export function AnchorProvider({
   toc,
   single = false,
+  observerOptions,
   children,
 }: AnchorProviderProps) {
   const observer = useMemo(() => new Observer(), [])
@@ -136,10 +140,16 @@ export function AnchorProvider({
   useEffect(() => {
     // We use a rootMargin that acts as an activation "line" near the top.
     // headings are "intersecting" (active=true) when they are BELOW this line.
-    observer.watch({
-      rootMargin: '-100px 0% 0% 0%',
+    // Default to a more permissive margin for detecting visible headings
+    const defaultOptions = {
+      rootMargin: '-80px 0% -60% 0%',
       threshold: 0,
-    })
+    }
+    const options = observerOptions
+      ? { ...defaultOptions, ...observerOptions }
+      : defaultOptions
+
+    observer.watch(options)
     observer.onChange = () => setItems([...observer.items])
 
     return () => {
@@ -156,7 +166,7 @@ export const OnThisPage = ({ children, className }: ComponentBase) => {
       className={cn(
         'sticky top-navbar hidden xl:flex flex-col shrink-0',
         'w-toc',
-        'py-8 pl-6 pr-4',
+        'py-4 pl-6 pr-4',
         className,
       )}
     >
@@ -168,10 +178,7 @@ export const OnThisPage = ({ children, className }: ComponentBase) => {
 const OnThisPageHeader = ({ children, className, ...props }: ComponentBase) => {
   return (
     <div
-      className={cn(
-        'mb-4 text-xs font-bold text-text-main',
-        className,
-      )}
+      className={cn('mb-4 text-xs font-bold text-body', className)}
       {...props}
     >
       {children}
@@ -192,7 +199,16 @@ const OnThisPageContent = ({
   return (
     <div
       ref={internalRef}
-      className={cn('relative overflow-y-auto boltdocs-otp-content', className)}
+      className={cn(
+        'relative overflow-y-auto boltdocs-otp-content pb-12',
+        'max-h-[70%]',
+        className,
+      )}
+      style={{
+        maskImage: 'linear-gradient(to bottom, black 90%, transparent 100%)',
+        WebkitMaskImage:
+          'linear-gradient(to bottom, black 90%, transparent 100%)',
+      }}
       {...props}
     >
       {children}
@@ -206,7 +222,7 @@ const OnThisPageList = ({ children, className }: ComponentBase) => {
   return (
     <ul
       className={cn(
-        'relative space-y-1 text-sm border-l border-border-subtle',
+        'relative space-y-0.5 text-sm border-l border-subtle',
         className,
       )}
     >
@@ -234,41 +250,49 @@ const OnThisPageLink = ({
   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
+  const computedActive =
+    active !== undefined
+      ? active
+      : id && items
+        ? !!items.find((i) => i.id === id)?.active
+        : false
+
   useEffect(() => {
-    if (active !== undefined) setInternalActive(active)
-  }, [active])
+    if (computedActive && anchorRef.current && containerRef?.current) {
+      scrollIntoView(anchorRef.current, {
+        behavior: 'smooth',
+        block: 'center',
+        inline: 'center',
+        scrollMode: 'if-needed',
+        boundary: containerRef.current,
+      })
+    }
+  }, [computedActive, containerRef])
+
+  const handleClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
+    if (onClick) {
+      onClick(e)
+    } else if (href && href.startsWith('#')) {
+      e.preventDefault()
+      const elementId = href.slice(1)
+      const el = document.getElementById(elementId)
+      if (el) {
+        el.scrollIntoView({ behavior: 'smooth' })
+        window.history.pushState(null, '', href)
+      }
+    }
+  }
 
   return (
     <a
       ref={anchorRef}
       href={href}
-      onClick={onClick}
-      data-active={internalActive}
+      onClick={handleClick}
+      data-active={computedActive}
       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',
+        'block py-0.5 pl-4 text-[13px] outline-none transition-colors',
+        computedActive ? 'text-primary-500' : 'text-muted hover:text-body',
         className,
       )}
     >
@@ -281,17 +305,118 @@ const OnThisPageIndicator = ({
   style,
   className,
 }: OnThisPageIndicatorProps) => {
+  const containerRef = useRef<HTMLDivElement>(null)
+  const [internalStyle, setInternalStyle] = useState<React.CSSProperties>({
+    opacity: 0,
+    ...style,
+  })
+
+  const items = useItems()
+
+  useEffect(() => {
+    const parent = containerRef.current?.parentElement
+    if (!parent) return
+
+    const activeLinks = parent.querySelectorAll('a[data-active="true"]')
+
+    if (activeLinks.length > 0) {
+      const firstActiveLink = activeLinks[0] as HTMLElement
+      const lastActiveLink = activeLinks[activeLinks.length - 1] as HTMLElement
+
+      const firstRect = firstActiveLink.getBoundingClientRect()
+      const lastRect = lastActiveLink.getBoundingClientRect()
+      const parentRect = parent.getBoundingClientRect()
+
+      const offsetTop = firstRect.top - parentRect.top
+      const height = lastRect.bottom - firstRect.top
+
+      setInternalStyle({
+        transform: `translateY(${offsetTop}px)`,
+        height: `${height}px`,
+        opacity: 1,
+        ...style,
+      })
+    } else {
+      setInternalStyle({
+        opacity: 0,
+        ...style,
+      })
+    }
+  }, [items, style])
+
   return (
     <div
+      ref={containerRef}
       className={cn(
-        'absolute -left-px w-0.5 rounded-full bg-primary-500 transition-all duration-300',
+        'absolute -left-px w-0.5 rounded-full bg-primary-500',
         className,
       )}
-      style={style}
+      style={{
+        transition:
+          'transform 180ms cubic-bezier(0.2, 0.8, 0.2, 1), height 180ms cubic-bezier(0.2, 0.8, 0.2, 1), opacity 150ms',
+        ...internalStyle,
+      }}
     />
   )
 }
 
+/**
+ * High-level automated list of toc items
+ */
+export function OnThisPageItems({
+  headings = [],
+  className,
+}: {
+  headings: { level: number; text: string; id: string }[]
+} & ComponentBase) {
+  const activeIds = useActiveAnchors()
+
+  if (headings.length === 0) return null
+
+  return (
+    <OnThisPageList className={className}>
+      <OnThisPageIndicator />
+      {headings.map((h) => (
+        <OnThisPageItem key={h.id} level={h.level}>
+          <OnThisPageLink href={`#${h.id}`} active={activeIds.includes(h.id)}>
+            {h.text}
+          </OnThisPageLink>
+        </OnThisPageItem>
+      ))}
+    </OnThisPageList>
+  )
+}
+
+/**
+ * High-level automated Table of Contents tree
+ */
+export function OnThisPageTree({
+  headings = [],
+  className,
+}: {
+  headings: { level: number; text: string; id: string }[]
+} & ComponentBase) {
+  const toc = useMemo(
+    () =>
+      headings.map((h) => ({ title: h.text, url: `#${h.id}`, depth: h.level })),
+    [headings],
+  )
+
+  const scrollContainerRef = useRef<HTMLDivElement>(null)
+
+  if (headings.length === 0) return null
+
+  return (
+    <AnchorProvider toc={toc} single={false}>
+      <ScrollProvider containerRef={scrollContainerRef}>
+        <OnThisPageContent ref={scrollContainerRef}>
+          <OnThisPageItems headings={headings} className={className} />
+        </OnThisPageContent>
+      </ScrollProvider>
+    </AnchorProvider>
+  )
+}
+
 OnThisPage.Root = OnThisPage
 OnThisPage.Header = OnThisPageHeader
 OnThisPage.Content = OnThisPageContent
@@ -299,3 +424,7 @@ OnThisPage.List = OnThisPageList
 OnThisPage.Item = OnThisPageItem
 OnThisPage.Link = OnThisPageLink
 OnThisPage.Indicator = OnThisPageIndicator
+OnThisPage.Items = OnThisPageItems
+OnThisPage.Tree = OnThisPageTree
+
+export default OnThisPage

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

@@ -1,4 +1,4 @@
-import * as RAC from 'react-aria-components'
+import { Link } from './link'
 import { ChevronLeft, ChevronRight } from 'lucide-react'
 import { cn } from '../../utils/cn'
 import type { ComponentBase } from './types'
@@ -10,62 +10,34 @@ export interface PageNavProps extends ComponentBase {
 
 export const PageNav = ({ 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>
+    <nav className={cn('grid sm:grid-cols-2 gap-4', className)}>{children}</nav>
   )
 }
 
 const PageNavLink = ({ children, to, direction, className }: PageNavProps) => {
   const isNext = direction === 'next'
   return (
-    <RAC.Link
+    <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',
+        'flex items-center outline-none no-underline',
+        isNext ? 'justify-end' : '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>
+      {!isNext && <ChevronLeft className="shrink-0" />}
+      <div className="flex flex-col flex-1">{children}</div>
+      {isNext && <ChevronRight className="shrink-0" />}
+    </Link>
   )
 }
 
 const PageNavTitle = ({ children, className }: ComponentBase) => {
-  return (
-    <span
-      className={cn(
-        'text-xs font-medium uppercase text-text-muted',
-        className,
-      )}
-    >
-      {children}
-    </span>
-  )
+  return <span className={cn(className)}>{children}</span>
 }
 
 const PageNavDescription = ({ children, className }: ComponentBase) => {
-  return (
-    <span
-      className={cn('text-base font-bold text-text-main truncate', className)}
-    >
-      {children}
-    </span>
-  )
+  return <span className={cn('truncate', className)}>{children}</span>
 }
 
 const PageNavIcon = ({ children }: ComponentBase) => {

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

@@ -1,46 +1,28 @@
-'use client'
-
-import * as RAC from 'react-aria-components'
+import {
+  Popover as RACPopover,
+  type PopoverProps as RACPopoverProps,
+} from 'react-aria-components'
 import { cn } from '../../utils/cn'
 
-export interface PopoverProps extends Omit<RAC.PopoverProps, 'children'> {
+export interface PopoverProps extends Omit<RACPopoverProps, '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) => {
+export const Popover = ({ children, className, ...props }: PopoverProps) => {
   return (
-    <RAC.Popover
+    <RACPopover
       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 transition-none',
-          className,
-        ),
+      className={cn(
+        'z-50 overflow-auto outline-none transition-none',
+        className,
       )}
+      {...props}
     >
-      {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>
+    </RACPopover>
   )
 }

package/src/client/components/primitives/search-dialog.tsx

@@ -1,13 +1,10 @@
+'use client'
+
 import * as RAC from 'react-aria-components'
-import { Search, Hash, FileText, CornerDownLeft } from 'lucide-react'
+import { Hash, FileText, CornerDownLeft } from 'lucide-react'
 import { cn } from '../../utils/cn'
 import type { ComponentBase } from './types'
 
-export interface SearchDialogProps extends ComponentBase {
-  isOpen?: boolean
-  onOpenChange?: (isOpen: boolean) => void
-}
-
 export interface SearchDialogItemProps
   extends Omit<RAC.ListBoxItemProps, 'children'> {
   className?: string
@@ -19,37 +16,66 @@ export interface SearchDialogItemIconProps {
   className?: string
 }
 
+/**
+ * Pure, unstyled SearchDialog Overlay (maps to RAC.ModalOverlay)
+ */
 export const SearchDialog = ({
-  children,
-  isOpen,
-  onOpenChange,
   className,
-}: SearchDialogProps) => {
+  ...props
+}: RAC.ModalOverlayProps) => {
   return (
     <RAC.ModalOverlay
-      isOpen={isOpen}
-      onOpenChange={onOpenChange}
-      isDismissable
-      className={cn(
-        'fixed inset-0 z-100 bg-black/40 backdrop-blur-sm px-4 py-4 sm:py-20',
-        'entering:animate-in entering:fade-in exiting:animate-out exiting:fade-out',
-      )}
-    >
-      <RAC.Modal
-        className={cn(
-          'mx-auto w-full max-w-2xl overflow-hidden rounded-xl border border-border-subtle bg-bg-surface shadow-2xl ring-1 ring-black/5 outline-none',
-          'entering:animate-in entering:fade-in entering:zoom-in-95 exiting:animate-out exiting:fade-out exiting:zoom-out-95',
-          className,
-        )}
-      >
-        <RAC.Dialog className="flex flex-col max-h-[70vh] focus:outline-none">
-          {children as any}
-        </RAC.Dialog>
-      </RAC.Modal>
-    </RAC.ModalOverlay>
+      className={cn('fixed inset-0 z-100', className)}
+      {...props}
+    />
   )
 }
 
+/**
+ * Pure, unstyled SearchDialog Content (maps to RAC.Modal)
+ */
+const SearchDialogContent = ({
+  className,
+  ...props
+}: RAC.ModalOverlayProps) => <RAC.Modal className={cn(className)} {...props} />
+
+/**
+ * Pure, unstyled SearchDialog Dialog (maps to RAC.Dialog)
+ */
+const SearchDialogDialog = ({ className, ...props }: RAC.DialogProps) => (
+  <RAC.Dialog
+    className={cn('flex flex-col focus:outline-none', className)}
+    {...props}
+  />
+)
+
+/**
+ * Pure, unstyled SearchDialog Input Field (maps to RAC.SearchField)
+ */
+const SearchDialogField = ({ className, ...props }: RAC.SearchFieldProps) => (
+  <RAC.SearchField className={cn('flex items-center', className)} {...props} />
+)
+
+/**
+ * Pure, unstyled SearchInput (maps to RAC.Input)
+ */
+const SearchDialogSearchInput = ({ className, ...props }: RAC.InputProps) => (
+  <RAC.Input
+    className={cn('w-full bg-transparent outline-none border-none', className)}
+    {...props}
+  />
+)
+
+/**
+ * Pure, unstyled Clear Button (maps to RAC.Button with slot="clear")
+ */
+const SearchDialogClearButton = ({ className, ...props }: RAC.ButtonProps) => (
+  <RAC.Button slot="clear" className={cn(className)} {...props} />
+)
+
+/**
+ * Pure, unstyled Autocomplete container (maps to RAC.Autocomplete)
+ */
 const SearchDialogAutocomplete = <T extends object>({
   children,
   className,
@@ -61,7 +87,7 @@ const SearchDialogAutocomplete = <T extends object>({
 }) => {
   const Autocomplete = RAC.Autocomplete as any
   return (
-    <div className={className}>
+    <div className={cn('flex-1 min-h-0', className)}>
       <Autocomplete
         {...props}
         onSelectionChange={onSelectionChange}
@@ -73,31 +99,9 @@ const SearchDialogAutocomplete = <T extends object>({
   )
 }
 
-const SearchDialogInput = ({
-  className,
-  ...props
-}: RAC.InputProps & { className?: string }) => {
-  return (
-    <RAC.SearchField
-      className="flex items-center gap-3 border-b border-border-subtle px-4 py-4"
-      autoFocus
-    >
-      <Search className="h-5 w-5 text-text-muted" />
-      <RAC.Input
-        {...props}
-        className={cn(
-          'w-full bg-transparent text-lg text-text-main placeholder-text-muted outline-none',
-          className,
-        )}
-        placeholder="Search documentation..."
-      />
-      <div className="flex items-center gap-1.5 rounded-md border border-border-subtle bg-bg-main px-1.5 py-1 text-[10px] font-medium text-text-muted">
-        <kbd className="font-sans">ESC</kbd>
-      </div>
-    </RAC.SearchField>
-  )
-}
-
+/**
+ * Pure, unstyled List Box (maps to RAC.ListBox)
+ */
 const SearchDialogList = <T extends object>({
   children,
   className,
@@ -106,13 +110,16 @@ const SearchDialogList = <T extends object>({
   return (
     <RAC.ListBox
       {...props}
-      className={cn('flex-1 overflow-y-auto p-2 outline-none', className)}
+      className={cn('flex-1 overflow-y-auto outline-none min-h-0', className)}
     >
       {children as any}
     </RAC.ListBox>
   )
 }
 
+/**
+ * Pure, unstyled List Box Item (maps to RAC.ListBoxItem)
+ */
 const SearchDialogItemRoot = ({
   children,
   className,
@@ -122,8 +129,7 @@ const SearchDialogItemRoot = ({
     <RAC.ListBoxItem
       {...props}
       className={cn(
-        'group flex items-center gap-3 rounded-lg p-3 text-left outline-none cursor-pointer transition-colors',
-        'text-text-muted hover:bg-bg-main hover:text-text-main focus:bg-primary-500 focus:text-white selected:bg-primary-500 selected:text-white',
+        'group flex items-center outline-none cursor-pointer',
         className,
       )}
     >
@@ -155,31 +161,31 @@ const SearchDialogItemIcon = ({
 
 const SearchDialogItemTitle = ({ children, className }: ComponentBase) => {
   return (
-    <span
-      className={cn('block font-medium truncate flex-1 text-sm', className)}
-    >
-      {children}
-    </span>
+    <span className={cn('block truncate flex-1', className)}>{children}</span>
   )
 }
 
 const SearchDialogItemBio = ({ children, className }: ComponentBase) => {
   return (
-    <span
-      className={cn(
-        'ml-2 text-xs opacity-70 truncate hidden sm:inline group-focus:opacity-100',
-        className,
-      )}
-    >
+    <span className={cn('ml-2 truncate hidden sm:inline', className)}>
       {children}
     </span>
   )
 }
 
+// Compound API wiring
 SearchDialog.Root = SearchDialog
+SearchDialog.Overlay = SearchDialog
+SearchDialog.Content = SearchDialogContent
+SearchDialog.Dialog = SearchDialogDialog
 SearchDialog.Autocomplete = SearchDialogAutocomplete
-SearchDialog.Input = SearchDialogInput
 SearchDialog.List = SearchDialogList
+
+SearchDialog.Input = Object.assign(SearchDialogField, {
+  SearchInput: SearchDialogSearchInput,
+  Button: SearchDialogClearButton,
+})
+
 SearchDialog.Item = Object.assign(SearchDialogItemRoot, {
   Icon: SearchDialogItemIcon,
   Title: SearchDialogItemTitle,