boltdocs 1.10.2 → 2.0.0

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>
+  )
+}

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

@@ -0,0 +1,192 @@
+import {
+  Children,
+  isValidElement,
+  type ReactNode,
+  type ReactElement,
+  type ComponentPropsWithoutRef,
+} from 'react'
+import { Check, ChevronRight, Circle } from 'lucide-react'
+import { cn } from '@client/utils/cn'
+import { cva, type VariantProps } from 'class-variance-authority'
+
+const listVariants = cva('my-6 transition-all duration-200', {
+  variants: {
+    variant: {
+      default: 'list-disc pl-5 text-text-muted marker:text-primary-500/50',
+      number:
+        'list-decimal pl-5 text-text-muted marker:text-primary-500/50 marker:font-bold',
+      checked: 'list-none p-0',
+      arrow: 'list-none p-0',
+      bubble: 'list-none p-0',
+    },
+    cols: {
+      1: 'grid-cols-1',
+      2: 'grid-cols-1 sm:grid-cols-2',
+      3: 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-3',
+      4: 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-4',
+    },
+    isGrid: {
+      true: 'grid gap-x-8 gap-y-3',
+      false: 'space-y-2',
+    },
+    dense: {
+      true: 'space-y-1',
+      false: 'space-y-2',
+    },
+  },
+  compoundVariants: [
+    {
+      variant: 'default',
+      dense: true,
+      className: 'space-y-0.5',
+    },
+  ],
+  defaultVariants: {
+    variant: 'default',
+    cols: 1,
+    isGrid: false,
+    dense: false,
+  },
+})
+
+const itemVariants = cva(
+  'group flex items-start gap-3 text-sm leading-relaxed transition-all duration-200',
+  {
+    variants: {
+      variant: {
+        default: '',
+        number: '',
+        checked: 'hover:translate-x-0.5',
+        arrow: 'hover:translate-x-0.5',
+        bubble: 'hover:translate-x-0.5',
+      },
+      dense: {
+        true: 'py-0',
+        false: 'py-0.5',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+      dense: false,
+    },
+  },
+)
+
+const iconContainerVariants = cva(
+  'mt-1 shrink-0 flex items-center justify-center transition-transform group-hover:scale-110',
+  {
+    variants: {
+      variant: {
+        bubble:
+          'h-5 w-5 rounded-full bg-primary-500/10 text-primary-500 text-[10px] font-bold',
+        default: '',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+    },
+  },
+)
+
+type ListVariantProps = VariantProps<typeof listVariants>
+
+export interface ListProps
+  extends ComponentPropsWithoutRef<'ul'>,
+    Omit<ListVariantProps, 'variant'> {
+  variant?: 'checked' | 'arrow' | 'default' | 'bubble' | 'number'
+  children: ReactNode
+}
+
+interface ListItemProps extends VariantProps<typeof itemVariants> {
+  icon?: ReactNode
+  children: ReactNode
+}
+
+function ListItem({ icon, children, variant, dense }: ListItemProps) {
+  return (
+    <li className={cn(itemVariants({ variant, dense }))}>
+      {icon && (
+        <span
+          className={cn(
+            iconContainerVariants({
+              variant: variant === 'bubble' ? 'bubble' : 'default',
+            }),
+          )}
+        >
+          {icon}
+        </span>
+      )}
+      <div className="flex-1 text-text-muted group-hover:text-text-main transition-colors">
+        {children}
+      </div>
+    </li>
+  )
+}
+
+const ICON_MAP: Record<string, (cls?: string) => ReactNode> = {
+  checked: (cls) => (
+    <Check size={14} className={cn('text-emerald-500 shrink-0', cls)} />
+  ),
+  arrow: (cls) => (
+    <ChevronRight size={14} className={cn('text-primary-400 shrink-0', cls)} />
+  ),
+  bubble: (cls) => (
+    <Circle
+      size={6}
+      fill="currentColor"
+      className={cn('text-primary-500 shrink-0', cls)}
+    />
+  ),
+  default: () => null,
+  number: () => null,
+}
+
+export function List({
+  variant = 'default',
+  cols = 1,
+  dense = false,
+  children,
+  className,
+  ...props
+}: ListProps) {
+  const isGrid = cols !== undefined && Number(cols) > 1
+  const renderIcon = ICON_MAP[variant]
+  const containerClasses = listVariants({
+    variant,
+    cols,
+    dense,
+    isGrid,
+    className,
+  })
+
+  const Component = variant === 'number' ? 'ol' : 'ul'
+
+  // Handling raw MDX siblings (nested logic)
+  if (variant === 'default' || variant === 'number') {
+    return (
+      <Component className={containerClasses} {...props}>
+        {children}
+      </Component>
+    )
+  }
+
+  return (
+    <ul className={containerClasses} {...props}>
+      {Children.map(children, (child) => {
+        if (!isValidElement(child)) return child
+
+        const element = child as ReactElement<{ children?: ReactNode }>
+        const content =
+          element.type === 'li'
+            ? element.props.children
+            : element.props.children || child
+
+        return (
+          <ListItem icon={renderIcon()} variant={variant} dense={dense}>
+            {content}
+          </ListItem>
+        )
+      })}
+    </ul>
+  )
+}

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

@@ -0,0 +1,156 @@
+import * as RAC from 'react-aria-components'
+import { useTable } from './hooks/useTable'
+import {
+  ChevronUp,
+  ChevronDown,
+  ChevronLeft,
+  ChevronRight,
+  ChevronsLeft,
+  ChevronsRight,
+} from 'lucide-react'
+import { cn } from '@client/utils/cn'
+
+export interface TableProps {
+  headers?: string[]
+  data?: (string | React.ReactNode)[][]
+  children?: React.ReactNode
+  className?: string
+  sortable?: boolean
+  paginated?: boolean
+  pageSize?: number
+}
+
+export function Table({
+  headers,
+  data,
+  children,
+  className = '',
+  sortable = false,
+  paginated = false,
+  pageSize = 10,
+}: TableProps) {
+  const {
+    sortConfig,
+    currentPage,
+    setCurrentPage,
+    totalPages,
+    paginatedData,
+    requestSort,
+  } = useTable({
+    data,
+    sortable,
+    paginated,
+    pageSize,
+  })
+
+  const renderSortIcon = (index: number) => {
+    if (!sortable) return null
+    if (sortConfig?.key !== index)
+      return <ChevronDown size={14} className="ml-1 opacity-30" />
+    return sortConfig.direction === 'asc' ? (
+      <ChevronUp size={14} className="ml-1 text-primary-400" />
+    ) : (
+      <ChevronDown size={14} className="ml-1 text-primary-400" />
+    )
+  }
+
+  const tableContent = children ? (
+    children
+  ) : (
+    <>
+      {headers && (
+        <thead>
+          <tr>
+            {headers.map((header, i) => (
+              <th
+                key={i}
+                onClick={() => requestSort(i)}
+                className={cn(
+                  'text-left px-3 py-2.5 border-b-2 border-border-subtle text-text-main font-semibold text-sm',
+                  sortable &&
+                    'cursor-pointer select-none hover:text-primary-400 transition-colors',
+                )}
+              >
+                <div className="flex items-center">
+                  {header}
+                  {renderSortIcon(i)}
+                </div>
+              </th>
+            ))}
+          </tr>
+        </thead>
+      )}
+      {paginatedData && (
+        <tbody>
+          {paginatedData.map((row, i) => (
+            <tr key={i} className="transition-colors hover:bg-bg-surface">
+              {row.map((cell, j) => (
+                <td
+                  key={j}
+                  className="px-3 py-2 border-b border-border-subtle text-sm text-text-muted"
+                >
+                  {cell}
+                </td>
+              ))}
+            </tr>
+          ))}
+        </tbody>
+      )}
+    </>
+  )
+
+  return (
+    <div
+      className={cn(
+        'my-6 rounded-lg border border-border-subtle overflow-hidden',
+        className,
+      )}
+    >
+      <div className="overflow-x-auto">
+        <table className="w-full border-collapse text-sm">{tableContent}</table>
+      </div>
+
+      {paginated && totalPages > 1 && (
+        <div className="flex items-center justify-between border-t border-border-subtle px-4 py-3">
+          <span className="text-xs text-text-muted">
+            Page {currentPage} of {totalPages}
+          </span>
+          <div className="flex items-center gap-1">
+            <RAC.Button
+              onPress={() => setCurrentPage(1)}
+              isDisabled={currentPage === 1}
+              className="grid place-items-center h-7 w-7 rounded-md text-text-muted outline-none transition-colors hover:bg-bg-surface disabled:opacity-30 disabled:pointer-events-none cursor-pointer"
+            >
+              <ChevronsLeft size={16} />
+            </RAC.Button>
+            <RAC.Button
+              onPress={() =>
+                setCurrentPage((prev: number) => Math.max(prev - 1, 1))
+              }
+              isDisabled={currentPage === 1}
+              className="grid place-items-center h-7 w-7 rounded-md text-text-muted outline-none transition-colors hover:bg-bg-surface disabled:opacity-30 disabled:pointer-events-none cursor-pointer"
+            >
+              <ChevronLeft size={16} />
+            </RAC.Button>
+            <RAC.Button
+              onPress={() =>
+                setCurrentPage((prev: number) => Math.min(prev + 1, totalPages))
+              }
+              isDisabled={currentPage === totalPages}
+              className="grid place-items-center h-7 w-7 rounded-md text-text-muted outline-none transition-colors hover:bg-bg-surface disabled:opacity-30 disabled:pointer-events-none cursor-pointer"
+            >
+              <ChevronRight size={16} />
+            </RAC.Button>
+            <RAC.Button
+              onPress={() => setCurrentPage(totalPages)}
+              isDisabled={currentPage === totalPages}
+              className="grid place-items-center h-7 w-7 rounded-md text-text-muted outline-none transition-colors hover:bg-bg-surface disabled:opacity-30 disabled:pointer-events-none cursor-pointer"
+            >
+              <ChevronsRight size={16} />
+            </RAC.Button>
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}