boltdocs 2.6.1 → 2.7.0

package/src/client/components/primitives/code-block.tsx

@@ -1,113 +1,120 @@
-import type { ComponentProps } from "react";
-import { cn } from "../../utils/cn";
+import type { ComponentProps } from 'react'
+import { cn } from '../../utils/cn'
 
-interface CodeBlockRootProps extends ComponentProps<"div"> {
-    /**
-     * Whether the code block is in plain mode (no borders/padding)
-     * @default false
-     */
-    plain?: boolean;
+interface CodeBlockRootProps extends ComponentProps<'div'> {
+  /**
+   * Whether the code block is in plain mode (no borders/padding)
+   * @default false
+   */
+  plain?: boolean
 }
 
+export interface CodeBlockHeaderProps extends ComponentProps<'div'> {}
+export interface CodeBlockGroupProps extends ComponentProps<'div'> {}
+export interface CodeBlockContentProps extends ComponentProps<'div'> {
+  /**
+   * Whether the code content should be truncated with an expand button
+   * @default false
+   */
+  shouldTruncate?: boolean
+}
+
+/**
+ * Root component for code blocks.
+ * Handles background, borders, and general layout.
+ */
 const CodeBlock = ({
-    children,
-    className,
-    plain = false,
-    ...props
+  children,
+  className,
+  plain = false,
+  ...props
 }: CodeBlockRootProps) => {
-    return (
-        <div
-            className={cn(
-                "not-prose boltdocs-code-block",
-                'group relative overflow-hidden bg-(--color-code-bg)',
-                'contain-layout contain-paint',
-                {
-                    'my-6 rounded-lg border border-border-subtle': !plain,
-                },
-                className,
-            )}
-            {...props}
-        >
-            {children}
-        </div>
-    );
-};
-
-type CodeBlockHeaderProps = ComponentProps<"div">;
+  return (
+    <div
+      className={cn(
+        'not-prose boltdocs-code-block',
+        'group relative overflow-hidden bg-(--color-code-bg)',
+        'contain-layout contain-paint',
+        {
+          'my-6 rounded-xl border border-subtle': !plain,
+        },
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </div>
+  )
+}
 
+/**
+ * Header section of the code block.
+ * Usually contains the title, language label, and action buttons.
+ */
 const CodeBlockHeader = ({
-    children,
-    className,
-    ...props
+  children,
+  className,
+  ...props
 }: CodeBlockHeaderProps) => {
-    return (
-        <div
-            className={cn(
-                "flex h-9 items-center justify-between px-4 py-1.5",
-                "border-b border-border-subtle bg-bg-surface/50",
-                "text-[13px] font-medium text-text-muted",
-                className,
-            )}
-            {...props}
-        >
-            {children}
-        </div>
-    );
-};
-
-type CodeBlockGroupProps = ComponentProps<"div">;
+  return (
+    <div
+      className={cn(
+        'flex h-9 items-center justify-between px-4 py-1.5',
+        'text-[13px] font-medium text-muted',
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </div>
+  )
+}
 
+/**
+ * Horizontal group for organizing items within the header (e.g., logo + label).
+ */
 const CodeBlockGroup = ({
-    children,
-    className,
-    ...props
+  children,
+  className,
+  ...props
 }: CodeBlockGroupProps) => {
-    return (
-        <div
-            className={cn(
-                "flex items-center space-x-2",
-                className,
-            )}
-            {...props}
-        >
-            {children}
-        </div>
-    );
-};
-
-interface CodeBlockContentProps extends ComponentProps<"div"> {
-    /**
-     * Whether the code should be truncated with an expand button
-     * @default false
-     */
-    shouldTruncate?: boolean;
+  return (
+    <div className={cn('flex items-center space-x-2', className)} {...props}>
+      {children}
+    </div>
+  )
 }
 
+/**
+ * Content area of the code block.
+ * Wraps the `<pre>` or `<div>` containing the code.
+ */
 const CodeBlockContent = ({
-    className,
-    children,
-    shouldTruncate = false,
-    ...props
+  className,
+  children,
+  shouldTruncate = false,
+  ...props
 }: CodeBlockContentProps) => {
-    return (
-        <div
-            className={cn(
-                "relative",
-                {
-                    '[&>pre]:max-h-62.5 [&>pre]:overflow-hidden': shouldTruncate,
-                },
-                className,
-            )}
-            {...props}
-        >
-            {children}
-        </div>
-    );
-};
+  return (
+    <div
+      className={cn(
+        'relative',
+        {
+          '[&>pre]:max-h-[300px] [&>pre]:overflow-hidden [&>div>pre]:max-h-[300px] [&>div>pre]:overflow-hidden':
+            shouldTruncate,
+        },
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </div>
+  )
+}
+
+// Assign sub-components
+CodeBlock.Header = CodeBlockHeader
+CodeBlock.Group = CodeBlockGroup
+CodeBlock.Content = CodeBlockContent
 
-export {
-    CodeBlock,
-    CodeBlockHeader,
-    CodeBlockGroup,
-    CodeBlockContent,
-};
+export { CodeBlock, CodeBlockHeader, CodeBlockGroup, CodeBlockContent }

package/src/client/components/{docs-layout.tsx → primitives/docs-layout.tsx}

@@ -1,5 +1,5 @@
-import { cn } from '../utils/cn'
-import { useLocation } from '../hooks'
+import { cn } from '../../utils/cn'
+import { SearchHighlight } from '../ui-base/search-highlight'
 
 /**
  * Props shared by all layout slot components.
@@ -25,7 +25,7 @@ function DocsLayoutRoot({ children, className, style }: SlotProps) {
   return (
     <div
       className={cn(
-        'h-screen flex flex-col overflow-hidden bg-bg-main text-text-main',
+        'h-screen flex flex-col overflow-hidden bg-main text-body',
         className,
       )}
       style={style}
@@ -42,7 +42,7 @@ function Body({ children, className, style }: SlotProps) {
   return (
     <div
       className={cn(
-        'mx-auto flex flex-1 w-full max-w-(--breakpoint-3xl) bg-bg-main overflow-hidden',
+        'mx-auto flex flex-1 w-full max-w-(--breakpoint-3xl) bg-main overflow-hidden',
         className,
       )}
       style={style}
@@ -74,41 +74,32 @@ function Content({ children, className, style }: SlotProps) {
  * MDX Content wrapper with standard page padding and max-width logic.
  */
 function ContentMdx({ children, className, style }: SlotProps) {
-  const { pathname } = useLocation()
   return (
     <div
-      className={cn(
-        'boltdocs-page mx-auto pt-4 pb-20 px-4 sm:px-8',
-        {
-          'max-w-content-max': pathname.includes('/docs/'),
-        },
-        className,
-      )}
+      className={cn('boltdocs-page mx-auto pt-4 pb-20 px-4 sm:px-8', className)}
       style={style}
     >
+      <SearchHighlight />
       {children}
     </div>
   )
 }
 
 /**
- * Content header row (breadcrumbs + copy markdown).
+ * Content header area (breadcrumbs, title, description, etc).
  */
-function ContentHeader({ children, className, style }: SlotProps) {
+function Header({ children, className, style }: SlotProps) {
   return (
-    <div
-      className={cn('flex items-center justify-between mb-10', className)}
-      style={style}
-    >
+    <header className={cn('mb-10', className)} style={style}>
       {children}
-    </div>
+    </header>
   )
 }
 
 /**
  * Footer area inside the content section (page nav).
  */
-function ContentFooter({ children, className, style }: SlotProps) {
+function Footer({ children, className, style }: SlotProps) {
   return (
     <div className={cn('mt-20', className)} style={style}>
       {children}
@@ -120,8 +111,8 @@ interface DocsLayoutComponent extends React.FC<SlotProps> {
   Body: typeof Body
   Content: typeof Content
   ContentMdx: typeof ContentMdx
-  ContentHeader: typeof ContentHeader
-  ContentFooter: typeof ContentFooter
+  Header: typeof Header
+  Footer: typeof Footer
 }
 
 // Attach sub-components to the root
@@ -129,6 +120,6 @@ export const DocsLayout = Object.assign(DocsLayoutRoot, {
   Body,
   Content,
   ContentMdx,
-  ContentHeader,
-  ContentFooter,
+  Header,
+  Footer,
 }) as DocsLayoutComponent

package/src/client/components/primitives/error-boundary.tsx

@@ -0,0 +1,107 @@
+import * as React from 'react'
+import type { ErrorInfo, ComponentType, ReactNode } from 'react'
+import { Component } from 'react'
+import { Button } from './button'
+
+export interface FallbackProps {
+  error: Error
+  resetErrorBoundary: () => void
+}
+
+export interface ErrorBoundaryProps {
+  children?: ReactNode
+  fallback?: ReactNode
+  FallbackComponent?: ComponentType<FallbackProps>
+  onError?: (error: Error, info: ErrorInfo) => void
+  onReset?: () => void
+}
+
+interface ErrorBoundaryState {
+  hasError: boolean
+  error: Error | null
+}
+
+export class ErrorBoundary extends Component<
+  ErrorBoundaryProps,
+  ErrorBoundaryState
+> {
+  public state: ErrorBoundaryState = { hasError: false, error: null }
+
+  public static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { hasError: true, error }
+  }
+
+  public componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    if (this.props.onError) {
+      this.props.onError(error, errorInfo)
+    } else {
+      console.error(
+        'ErrorBoundary caught an unhandled error:',
+        error,
+        errorInfo,
+      )
+    }
+  }
+
+  public resetErrorBoundary = () => {
+    if (this.props.onReset) {
+      this.props.onReset()
+    }
+    this.setState({ hasError: false, error: null })
+  }
+
+  public render() {
+    const { hasError, error } = this.state
+    const { children, fallback, FallbackComponent } = this.props
+
+    if (hasError && error) {
+      if (FallbackComponent) {
+        return (
+          <FallbackComponent
+            error={error}
+            resetErrorBoundary={this.resetErrorBoundary}
+          />
+        )
+      }
+      if (fallback) {
+        return fallback
+      }
+      return (
+        <ErrorBoundaryFallback
+          error={error}
+          resetErrorBoundary={this.resetErrorBoundary}
+        />
+      )
+    }
+
+    return children
+  }
+}
+
+export interface ErrorBoundaryFallbackProps {
+  error: Error
+  resetErrorBoundary: () => void
+}
+
+export function ErrorBoundaryFallback({
+  error,
+  resetErrorBoundary,
+}: ErrorBoundaryFallbackProps) {
+  return (
+    <div className="flex flex-col items-center justify-center min-h-[40vh] text-center gap-4 px-6 py-8 border border-subtle bg-surface rounded-2xl max-w-lg mx-auto shadow-xs">
+      <div className="text-lg font-bold text-rose-600 dark:text-rose-400">
+        Something went wrong
+      </div>
+      <p className="text-sm text-muted max-w-sm leading-relaxed">
+        {error?.message ||
+          'An unexpected error occurred while rendering this page.'}
+      </p>
+      <Button
+        className="rounded-xl border border-subtle bg-main px-6 py-2.5 text-xs font-semibold text-body hover:bg-primary-50/50 hover:border-primary-500/50 transition-all duration-300 cursor-pointer outline-none select-none"
+        onPress={resetErrorBoundary}
+      >
+        Try again
+      </Button>
+    </div>
+  )
+}

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

@@ -0,0 +1,128 @@
+import * as React from 'react'
+import { Link as LucideLink } from 'lucide-react'
+import { Link } from './link'
+import { cn } from '../../utils/cn'
+
+export interface HeadingProps extends React.HTMLAttributes<HTMLHeadingElement> {
+  level: 1 | 2 | 3 | 4 | 5 | 6
+  id?: string
+  /** Whether to show the anchor icon/link. Defaults to true if id is provided. */
+  showAnchor?: boolean
+  /** Position of the anchor link relative to children. Defaults to 'wrap'. */
+  anchorPosition?: 'wrap' | 'after' | 'before'
+  /** Custom icon to display for the anchor. */
+  anchorIcon?: React.ReactNode
+  /** Custom classes for the anchor link wrapper. */
+  anchorClassName?: string
+}
+
+export const Heading = React.forwardRef<HTMLHeadingElement, HeadingProps>(
+  (
+    {
+      level,
+      id,
+      children,
+      className,
+      showAnchor = true,
+      anchorPosition = 'wrap',
+      anchorIcon,
+      anchorClassName,
+      ...props
+    },
+    ref,
+  ) => {
+    const safeLevel = Math.min(Math.max(Math.floor(level), 1), 6) as
+      | 1
+      | 2
+      | 3
+      | 4
+      | 5
+      | 6
+    const Tag = `h${safeLevel}` as const
+
+    const hasAnchor = !!(id && showAnchor)
+
+    // Default icon with hover transition
+    const defaultIcon = (
+      <LucideLink
+        className={cn(
+          'transition-all duration-200',
+          anchorPosition === 'wrap'
+            ? 'opacity-0 ml-2 text-muted/50 group-hover:text-primary-500 group-hover:opacity-100'
+            : 'text-muted/50 hover:text-primary-500',
+        )}
+        size={16}
+      />
+    )
+
+    const icon = anchorIcon ?? defaultIcon
+
+    const renderContent = () => {
+      if (!hasAnchor) {
+        return children
+      }
+
+      if (anchorPosition === 'wrap') {
+        return (
+          <Link
+            href={`#${id}`}
+            className={cn(
+              'header-anchor flex flex-row items-center no-underline text-inherit',
+              anchorClassName,
+            )}
+            aria-label="Anchor"
+          >
+            {children}
+            {icon}
+          </Link>
+        )
+      }
+
+      return (
+        <>
+          {anchorPosition === 'before' && (
+            <Link
+              href={`#${id}`}
+              className={cn(
+                'header-anchor mr-2 opacity-0 group-hover:opacity-100 transition-opacity duration-200',
+                anchorClassName,
+              )}
+              aria-label="Anchor"
+            >
+              {icon}
+            </Link>
+          )}
+          {children}
+          {anchorPosition === 'after' && (
+            <Link
+              href={`#${id}`}
+              className={cn(
+                'header-anchor ml-2 opacity-0 group-hover:opacity-100 transition-opacity duration-200',
+                anchorClassName,
+              )}
+              aria-label="Anchor"
+            >
+              {icon}
+            </Link>
+          )}
+        </>
+      )
+    }
+
+    return (
+      <Tag
+        ref={ref}
+        id={id}
+        className={cn(
+          'boltdocs-heading relative group flex items-center scroll-mt-24',
+          className,
+        )}
+        {...props}
+      >
+        {renderContent()}
+      </Tag>
+    )
+  },
+)
+
+Heading.displayName = 'Heading'

package/src/client/components/primitives/helpers/observer.ts

@@ -11,45 +11,75 @@ export class Observer {
   private observer: IntersectionObserver | null = null
   onChange?: () => void
 
-  private callback(entries: IntersectionObserverEntry[]) {
-    if (entries.length === 0) return
-
-    // 1. Update internal state based on current intersection and position
-    for (const entry of entries) {
-      const item = this.items.find((i) => i.id === entry.target.id)
-      if (item) {
-        // item.active will track if the heading is currently "on or below" the trigger line
-        item.active = entry.isIntersecting
-
-        // item.fallback will track if the heading has scrolled "above" the trigger line
-        // RootMargin top is -100px, so trigger line is at 100px.
-        const activationLine = 100
-        item.fallback =
-          !entry.isIntersecting && entry.boundingClientRect.top < activationLine
+  private callback(_entries: IntersectionObserverEntry[]) {
+    // For each item, check if it's currently in viewport
+    for (const item of this.items) {
+      const element = document.getElementById(item.id)
+      if (!element) {
+        item.active = false
+        item.fallback = false
+        continue
       }
+
+      const rect = element.getBoundingClientRect()
+      const viewportHeight =
+        typeof window !== 'undefined' ? window.innerHeight : 1000
+
+      // Check if element is currently in viewport (visible)
+      // rect.bottom > 0
+      // rect.top < viewportHeight:
+      const isInViewport = rect.bottom > 0 && rect.top < viewportHeight
+
+      // Update active state based on current position
+      item.active = isInViewport
+
+      // Fallback: element has scrolled past but is still near viewport
+      item.fallback =
+        !isInViewport && rect.top > 0 && rect.top < viewportHeight * 2
     }
 
-    // 2. The active heading is the LAST one in document order that has scrolled past the line.
-    let highlightIdx = -1
-    for (let i = this.items.length - 1; i >= 0; i--) {
-      if (this.items[i].fallback) {
-        highlightIdx = i
-        break
+    // 3. Determine which items should be active based on single mode
+    if (this.single) {
+      // Single mode: only ONE active item (the one closest to the top of viewport)
+      let highlightIdx = -1
+
+      // Find all visible items and pick the one closest to the top of viewport
+      const visibleItems = this.items
+        .map((item, idx) => ({ item, idx }))
+        .filter(({ item }) => item.active)
+
+      if (visibleItems.length > 0) {
+        // Take the first one (closest to top of viewport)
+        highlightIdx = visibleItems[0].idx
+      } else {
+        // If nothing visible, check fallback items
+        const fallbackItems = this.items
+          .map((item, idx) => ({ item, idx }))
+          .filter(({ item }) => item.fallback)
+
+        if (fallbackItems.length > 0) {
+          highlightIdx = fallbackItems[0].idx
+        } else if (this.items.length > 0) {
+          highlightIdx = 0
+        }
       }
-    }
 
-    // 3. Initial state: If no headings have passed the line yet, default to the first heading.
-    if (highlightIdx === -1 && this.items.length > 0) {
-      highlightIdx = 0
+      // Map back to UI state - only one active
+      this.items = this.items.map((item, idx) => ({
+        ...item,
+        active: idx === highlightIdx,
+        t: idx === highlightIdx ? Date.now() : item.t,
+      }))
+    } else {
+      // Multi mode: items active when they are in viewport
+      // This ensures items activate when visible and deactivate when they leave viewport
+      this.items = this.items.map((item, idx) => ({
+        ...item,
+        active: item.active,
+        t: item.active ? Date.now() : item.t,
+      }))
     }
 
-    // 4. Map back to UI state
-    this.items = this.items.map((item, idx) => ({
-      ...item,
-      active: idx === highlightIdx,
-      t: idx === highlightIdx ? Date.now() : item.t,
-    }))
-
     this.onChange?.()
   }
 

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

@@ -0,0 +1,26 @@
+import type { ImgHTMLAttributes } from 'react'
+import { useTheme } from '../../app/theme-context'
+import { cn } from '../../utils/cn'
+
+export interface ImageProps extends ImgHTMLAttributes<HTMLImageElement> {
+  theme?: 'light' | 'dark'
+}
+
+/**
+ * A responsive image component that automatically supports dark and light theme variations
+ * via the `theme` prop.
+ */
+export function Image({ theme, className, ...props }: ImageProps) {
+  const { resolvedTheme } = useTheme()
+
+  if (theme && theme !== resolvedTheme) {
+    return null
+  }
+
+  return (
+    <img
+      className={cn('max-w-full h-auto rounded-lg my-8', className)}
+      {...props}
+    />
+  )
+}