boltdocs 1.10.2 → 1.11.0

package/src/client/components/mdx/file-tree.tsx

@@ -0,0 +1,287 @@
+import { Children, isValidElement, useMemo } from 'react'
+import * as RAC from 'react-aria-components'
+import {
+  Folder,
+  FileText,
+  File,
+  FileCode,
+  FileImage,
+  ChevronRight,
+} from 'lucide-react'
+import { cn } from '@client/utils/cn'
+
+// --- Constants & Types ---
+
+const ICON_SIZE = 16
+const STROKE_WIDTH = 2
+
+const FILE_REGEXES = {
+  CODE: /\.(ts|tsx|js|jsx|json|mjs|cjs|astro|vue|svelte)$/i,
+  TEXT: /\.(md|mdx|txt)$/i,
+  IMAGE: /\.(png|jpg|jpeg|svg|gif)$/i,
+} as const
+
+export interface FileTreeProps {
+  children: React.ReactNode
+}
+
+interface TreeItemData {
+  id: string
+  name: string
+  comment?: string
+  isFolder: boolean
+  children?: TreeItemData[]
+}
+
+// --- Helpers ---
+
+function getTextContent(node: React.ReactNode): string {
+  if (typeof node === 'string') return node
+  if (typeof node === 'number') return node.toString()
+  if (Array.isArray(node)) return node.map(getTextContent).join('')
+  if (
+    isValidElement(node) &&
+    node.props &&
+    typeof node.props === 'object' &&
+    'children' in node.props
+  ) {
+    return getTextContent(
+      (node.props as { children?: React.ReactNode }).children,
+    )
+  }
+  return ''
+}
+
+function getFileIcon(filename: string, isFolder: boolean) {
+  const name = filename.toLowerCase()
+  const iconClass = 'shrink-0 transition-colors duration-200'
+
+  if (isFolder) {
+    return (
+      <Folder
+        size={ICON_SIZE}
+        strokeWidth={STROKE_WIDTH}
+        className={cn(iconClass, 'text-primary-400')}
+        fill="currentColor"
+        fillOpacity={0.15}
+      />
+    )
+  }
+
+  const fileIconClass = cn(
+    iconClass,
+    'text-text-dim group-hover:text-text-main',
+  )
+
+  if (FILE_REGEXES.CODE.test(name))
+    return (
+      <FileCode
+        size={ICON_SIZE}
+        strokeWidth={STROKE_WIDTH}
+        className={fileIconClass}
+      />
+    )
+  if (FILE_REGEXES.TEXT.test(name))
+    return (
+      <FileText
+        size={ICON_SIZE}
+        strokeWidth={STROKE_WIDTH}
+        className={fileIconClass}
+      />
+    )
+  if (FILE_REGEXES.IMAGE.test(name))
+    return (
+      <FileImage
+        size={ICON_SIZE}
+        strokeWidth={STROKE_WIDTH}
+        className={fileIconClass}
+      />
+    )
+
+  return (
+    <File
+      size={ICON_SIZE}
+      strokeWidth={STROKE_WIDTH}
+      className={fileIconClass}
+    />
+  )
+}
+
+function isListElement(
+  node: unknown,
+  tag: 'ul' | 'li',
+): node is React.ReactElement<{ children?: React.ReactNode }> {
+  if (!isValidElement(node)) return false
+
+  const type = node.type
+  if (typeof type === 'string') return type === tag
+  if (typeof type === 'function') {
+    return type.name === tag || type.name?.toLowerCase() === tag
+  }
+
+  const props = node.props as any
+  return props?.originalType === tag || props?.mdxType === tag
+}
+
+function parseLabel(rawLabel: string): { name: string; comment?: string } {
+  const commentMatch = rawLabel.match(/\s+(\/\/|#)\s+(.*)$/)
+  if (commentMatch) {
+    return {
+      name: rawLabel.slice(0, commentMatch.index).trim(),
+      comment: commentMatch[2],
+    }
+  }
+  return { name: rawLabel.trim() }
+}
+
+function parseMdxToData(
+  node: React.ReactNode,
+  path: string = 'root',
+): TreeItemData[] {
+  if (!isValidElement(node)) return []
+
+  const items: TreeItemData[] = []
+
+  if (isListElement(node, 'ul')) {
+    Children.forEach(
+      (node.props as { children?: React.ReactNode }).children,
+      (child, index) => {
+        items.push(...parseMdxToData(child, `${path}-${index}`))
+      },
+    )
+    return items
+  }
+
+  if (isListElement(node, 'li')) {
+    const children = Children.toArray(
+      (node.props as { children?: React.ReactNode }).children,
+    )
+    const nestedListIndex = children.findIndex((child) =>
+      isListElement(child, 'ul'),
+    )
+
+    const hasNested = nestedListIndex !== -1
+    const labelNodes = hasNested ? children.slice(0, nestedListIndex) : children
+    const nestedNodes = hasNested ? children.slice(nestedListIndex) : []
+
+    const rawLabelContent = getTextContent(labelNodes)
+    const { name, comment } = parseLabel(rawLabelContent)
+
+    const isExplicitDir = name.endsWith('/')
+    const labelText = isExplicitDir ? name.slice(0, -1) : name
+    const isFolder = hasNested || isExplicitDir
+
+    items.push({
+      id: `${path}-${labelText}`,
+      name: labelText,
+      comment,
+      isFolder,
+      children: hasNested
+        ? parseMdxToData(nestedNodes[0], `${path}-${labelText}`)
+        : undefined,
+    })
+    return items
+  }
+
+  if (
+    node.props &&
+    typeof node.props === 'object' &&
+    'children' in node.props
+  ) {
+    Children.forEach(
+      (node.props as { children?: React.ReactNode }).children,
+      (child, index) => {
+        items.push(...parseMdxToData(child, `${path}-${index}`))
+      },
+    )
+  }
+
+  return items
+}
+
+// --- Sub-Components ---
+
+function FileTreeNode({ item }: { item: TreeItemData }) {
+  return (
+    <RAC.TreeItem
+      id={item.id}
+      textValue={item.name}
+      className="outline-none group focus-visible:ring-2 focus-visible:ring-primary-500/30 rounded-md"
+    >
+      <RAC.TreeItemContent>
+        {({ isExpanded, hasChildItems }) => (
+          <div className="flex items-center gap-2 py-1 px-1.5 rounded-md transition-colors hover:bg-primary-500/5 cursor-pointer">
+            <div
+              style={{ width: `calc((var(--tree-item-level) - 1) * 1rem)` }}
+              className="shrink-0"
+            />
+            {hasChildItems ? (
+              <RAC.Button
+                slot="chevron"
+                className="outline-none text-text-dim hover:text-primary-400 p-0.5 rounded transition-colors"
+              >
+                <ChevronRight
+                  size={14}
+                  strokeWidth={3}
+                  className={cn(
+                    'transition-transform duration-200',
+                    isExpanded && 'rotate-90',
+                  )}
+                />
+              </RAC.Button>
+            ) : (
+              <div className="w-[18px]" />
+            )}
+
+            {getFileIcon(item.name, item.isFolder)}
+
+            <span
+              className={cn(
+                'text-sm transition-colors truncate select-none',
+                item.isFolder
+                  ? 'font-semibold text-text-main'
+                  : 'text-text-muted group-hover:text-text-main',
+              )}
+            >
+              {item.name}
+            </span>
+
+            {item.comment && (
+              <span className="ml-2 text-xs italic text-text-dim opacity-70 group-hover:opacity-100 transition-opacity whitespace-nowrap overflow-hidden text-ellipsis font-sans">
+                {'//'} {item.comment}
+              </span>
+            )}
+          </div>
+        )}
+      </RAC.TreeItemContent>
+
+      {item.children && (
+        <RAC.Collection items={item.children}>
+          {(child) => <FileTreeNode item={child} />}
+        </RAC.Collection>
+      )}
+    </RAC.TreeItem>
+  )
+}
+
+// --- Main Component ---
+
+export function FileTree({ children }: FileTreeProps) {
+  const items = useMemo(() => parseMdxToData(children), [children])
+
+  return (
+    <div className="my-8">
+      <RAC.Tree
+        items={items}
+        aria-label="File Tree"
+        className={cn(
+          'rounded-xl border border-border-subtle bg-bg-surface/50 p-4 font-mono text-sm shadow-sm backdrop-blur-sm outline-none',
+          'max-h-[500px] overflow-y-auto scrollbar-thin scrollbar-thumb-border-subtle',
+          'focus-visible:ring-2 focus-visible:ring-primary-500/20',
+        )}
+      >
+        {(item) => <FileTreeNode item={item} />}
+      </RAC.Tree>
+    </div>
+  )
+}

package/src/client/components/mdx/hooks/use-code-block.ts

@@ -0,0 +1,56 @@
+import { useConfig } from '@client/app/config-context'
+import { openSandbox } from '@client/integrations/codesandbox'
+import { copyToClipboard } from '@client/utils/copy-clipboard'
+import { useCallback, useEffect, useRef, useState } from 'react'
+import type { CodeBlockProps } from '../code-block'
+
+export function useCodeBlock(props: CodeBlockProps) {
+  const { title, sandbox: localSandbox } = props
+  const [copied, setCopied] = useState(false)
+  const [isExpanded, setIsExpanded] = useState(false)
+  const [isExpandable, setIsExpandable] = useState(false)
+  const preRef = useRef<HTMLPreElement>(null)
+  const config = useConfig()
+
+  const handleCopy = useCallback(async () => {
+    const code = preRef.current?.textContent ?? ''
+    copyToClipboard(code)
+    setCopied(true)
+    setTimeout(() => setCopied(false), 2000)
+  }, [])
+
+  const handleSandbox = useCallback(() => {
+    const code = preRef.current?.textContent ?? ''
+    const globalSandbox = config?.integrations?.sandbox?.config || {}
+    const baseOptions =
+      typeof localSandbox === 'object' ? localSandbox : globalSandbox
+
+    const entry = baseOptions.entry || 'src/App.tsx'
+
+    openSandbox({
+      title: title ?? 'Code Snippet',
+      ...baseOptions,
+      files: {
+        ...baseOptions.files,
+        [entry]: { content: code },
+      },
+    })
+  }, [title, config, localSandbox])
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: updates when content changes
+  useEffect(() => {
+    const codeLength = preRef.current?.textContent?.length ?? 0
+    setIsExpandable(codeLength > 120)
+  }, [props.children, props.highlightedHtml])
+
+  return {
+    copied,
+    isExpanded,
+    setIsExpanded,
+    isExpandable,
+    preRef,
+    handleCopy,
+    handleSandbox,
+    shouldTruncate: isExpandable && !isExpanded,
+  }
+}

package/src/client/components/mdx/hooks/use-component-preview.ts

@@ -0,0 +1,16 @@
+import { useMemo } from 'react'
+import type { ComponentPreviewProps } from '../component-preview'
+
+export function useComponentPreview(props: ComponentPreviewProps) {
+  const { code: propsCode, children, preview } = props
+  const initialCode = useMemo(() => {
+    const base = propsCode ?? (typeof children === 'string' ? children : '')
+    return base.trim()
+  }, [propsCode, children])
+
+  const previewElement = useMemo(() => {
+    return preview ?? (typeof children !== 'string' ? children : null)
+  }, [preview, children])
+
+  return { initialCode, previewElement }
+}

package/src/client/components/mdx/hooks/useTable.ts

@@ -0,0 +1,74 @@
+import { useState, useMemo } from 'react'
+
+interface SortConfig {
+  key: number
+  direction: 'asc' | 'desc'
+}
+
+interface UseTableProps {
+  data?: (string | React.ReactNode)[][]
+  sortable?: boolean
+  paginated?: boolean
+  pageSize?: number
+}
+
+export function useTable({
+  data,
+  sortable = false,
+  paginated = false,
+  pageSize = 10,
+}: UseTableProps) {
+  const [sortConfig, setSortConfig] = useState<SortConfig | null>(null)
+  const [currentPage, setCurrentPage] = useState(1)
+
+  const processedData = useMemo(() => {
+    if (!data) return []
+    const items = [...data]
+
+    if (sortable && sortConfig !== null) {
+      items.sort((a, b) => {
+        const aVal = a[sortConfig.key]
+        const bVal = b[sortConfig.key]
+
+        const aStr = typeof aVal === 'string' ? aVal : ''
+        const bStr = typeof bVal === 'string' ? bVal : ''
+
+        if (aStr < bStr) return sortConfig.direction === 'asc' ? -1 : 1
+        if (aStr > bStr) return sortConfig.direction === 'asc' ? 1 : -1
+        return 0
+      })
+    }
+
+    return items
+  }, [data, sortConfig, sortable])
+
+  const totalPages = Math.ceil(processedData.length / pageSize)
+
+  const paginatedData = useMemo(() => {
+    if (!paginated) return processedData
+    const start = (currentPage - 1) * pageSize
+    return processedData.slice(start, start + pageSize)
+  }, [processedData, paginated, currentPage, pageSize])
+
+  const requestSort = (index: number) => {
+    if (!sortable) return
+    let direction: 'asc' | 'desc' = 'asc'
+    if (
+      sortConfig &&
+      sortConfig.key === index &&
+      sortConfig.direction === 'asc'
+    ) {
+      direction = 'desc'
+    }
+    setSortConfig({ key: index, direction })
+  }
+
+  return {
+    sortConfig,
+    currentPage,
+    setCurrentPage,
+    totalPages,
+    paginatedData,
+    requestSort,
+  }
+}

package/src/client/components/mdx/hooks/useTabs.ts

@@ -0,0 +1,68 @@
+import {
+  useState,
+  useRef,
+  useEffect,
+  useCallback,
+  type ReactElement,
+  type KeyboardEvent,
+} from 'react'
+
+interface UseTabsProps {
+  initialIndex?: number
+  tabs: ReactElement<any>[]
+}
+
+export function useTabs({ initialIndex = 0, tabs }: UseTabsProps) {
+  const defaultActive = tabs[initialIndex]?.props.disabled
+    ? tabs.findIndex((t) => !t.props.disabled)
+    : initialIndex
+
+  const [active, setActive] = useState(defaultActive === -1 ? 0 : defaultActive)
+  const tabRefs = useRef<(HTMLButtonElement | null)[]>([])
+  const [indicatorStyle, setIndicatorStyle] = useState<React.CSSProperties>({
+    opacity: 0,
+    transform: 'translateX(0)',
+    width: 0,
+  })
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: updates when content changes
+  useEffect(() => {
+    const activeTab = tabRefs.current[active]
+    if (activeTab) {
+      setIndicatorStyle({
+        opacity: 1,
+        width: activeTab.offsetWidth,
+        transform: `translateX(${activeTab.offsetLeft}px)`,
+      })
+    }
+  }, [active, tabs])
+
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLDivElement>) => {
+      let direction = 0
+      if (e.key === 'ArrowRight') direction = 1
+      else if (e.key === 'ArrowLeft') direction = -1
+
+      if (direction !== 0) {
+        let nextIndex = (active + direction + tabs.length) % tabs.length
+        while (tabs[nextIndex].props.disabled && nextIndex !== active) {
+          nextIndex = (nextIndex + direction + tabs.length) % tabs.length
+        }
+
+        if (nextIndex !== active && !tabs[nextIndex].props.disabled) {
+          setActive(nextIndex)
+          tabRefs.current[nextIndex]?.focus()
+        }
+      }
+    },
+    [active, tabs],
+  )
+
+  return {
+    active,
+    setActive,
+    tabRefs,
+    indicatorStyle,
+    handleKeyDown,
+  }
+}

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

@@ -0,0 +1,23 @@
+import type { ImgHTMLAttributes } from 'react'
+import { useTheme } from '@client/app/theme-context'
+
+export interface ImageProps extends ImgHTMLAttributes<HTMLImageElement> {
+  src: string
+  darkSrc?: string
+  theme?: 'light' | 'dark'
+}
+
+/**
+ * A themed Image component for Boltdocs.
+ * It supports rendering based on the current active theme.
+ */
+export function Image({ src, alt, theme: imageTheme, ...props }: ImageProps) {
+  const { theme: currentTheme } = useTheme()
+
+  // If a specific theme is required for this image, only render if it matches
+  if (imageTheme && imageTheme !== currentTheme) {
+    return null
+  }
+
+  return <img src={src} alt={alt || ''} {...props} />
+}

package/src/client/components/mdx/index.ts

@@ -0,0 +1,53 @@
+export { Button } from './button'
+export type { ButtonProps } from './button'
+
+export { CodeBlock } from './code-block'
+
+export { Tabs, Tab } from './tabs'
+export type { TabsProps, TabProps } from './tabs'
+
+export { Video } from './video'
+
+export { Badge } from './badge'
+export type { BadgeProps } from './badge'
+
+export { Card, Cards } from './card'
+export type { CardProps, CardsProps } from './card'
+
+export {
+  Admonition,
+  Note,
+  Tip,
+  Warning,
+  Danger,
+  InfoBox,
+  Important,
+  Caution,
+} from './admonition'
+export type { AdmonitionProps } from './admonition'
+
+export { List } from './list'
+export type { ListProps } from './list'
+
+export { FileTree } from './file-tree'
+export type { FileTreeProps } from './file-tree'
+
+export { Table } from './table'
+export type { TableProps } from './table'
+
+export { Field } from './field'
+export type { FieldProps } from './field'
+
+export { Link } from './link'
+export type { LinkProps } from './link'
+
+export { Image } from './image'
+export type { ImageProps } from './image'
+
+export { ComponentProps } from './component-props'
+export type { ComponentPropsProps } from './component-props'
+
+export { ComponentPreview } from './component-preview'
+export type { ComponentPreviewProps } from './component-preview'
+export { CopyMarkdown } from '../ui-base/copy-markdown'
+export type { CopyMarkdownProps } from '../ui-base/copy-markdown'

package/src/client/components/mdx/link.tsx

@@ -0,0 +1,38 @@
+import {
+  Link as LinkPrimitive,
+  type LinkProps as LinkPrimitiveProps,
+} from '@components/primitives/link'
+import { cn } from '@client/utils/cn'
+
+export type LinkProps = LinkPrimitiveProps & {
+  to: string
+  children?: React.ReactNode
+}
+
+/**
+ * A premium Link component for Boltdocs that handles internal and external routing.
+ */
+export function Link({ to, children, className = '', ...props }: LinkProps) {
+  const isExternal =
+    to &&
+    (to.startsWith('http://') ||
+      to.startsWith('https://') ||
+      to.startsWith('//'))
+
+  const combinedClassName = cn(
+    'text-blue-600 hover:text-blue-800 hover:underline cursor-pointer',
+    className,
+  )
+
+  return (
+    <LinkPrimitive
+      href={to}
+      className={combinedClassName}
+      target={isExternal ? '_blank' : undefined}
+      rel={isExternal ? 'noopener noreferrer' : undefined}
+      {...props}
+    >
+      {children}
+    </LinkPrimitive>
+  )
+}