@mdxui/payload 6.0.1

package/src/mdx-preview/useMDXCompiler.ts

@@ -0,0 +1,95 @@
+'use client'
+
+import { useState, useEffect, useCallback, useRef } from 'react'
+import { compile } from '@mdx-js/mdx'
+
+export interface MDXCompilerOptions {
+  /** MDX source code to compile */
+  source: string
+  /** Debounce delay in milliseconds (default: 300) */
+  debounceMs?: number
+  /** Whether to enable development mode (default: true) */
+  development?: boolean
+}
+
+export interface MDXCompilerResult {
+  /** Compiled MDX code (ES module string) */
+  code: string | null
+  /** Compilation error if any */
+  error: Error | null
+  /** Whether compilation is in progress */
+  isCompiling: boolean
+}
+
+/**
+ * Hook for compiling MDX source code with debouncing support.
+ *
+ * @example
+ * ```tsx
+ * const { code, error, isCompiling } = useMDXCompiler({
+ *   source: mdxSource,
+ *   debounceMs: 300,
+ * })
+ * ```
+ */
+export function useMDXCompiler({
+  source,
+  debounceMs = 300,
+  development = true,
+}: MDXCompilerOptions): MDXCompilerResult {
+  const [code, setCode] = useState<string | null>(null)
+  const [error, setError] = useState<Error | null>(null)
+  const [isCompiling, setIsCompiling] = useState(false)
+  const timeoutRef = useRef<NodeJS.Timeout | null>(null)
+
+  const compileMDX = useCallback(async (mdxSource: string) => {
+    if (!mdxSource.trim()) {
+      setCode(null)
+      setError(null)
+      setIsCompiling(false)
+      return
+    }
+
+    setIsCompiling(true)
+    setError(null)
+
+    try {
+      const compiled = await compile(mdxSource, {
+        outputFormat: 'function-body',
+        development,
+        /* @ts-ignore - MDX types are complex */
+        providerImportSource: '@mdx-js/react',
+      })
+
+      setCode(String(compiled))
+      setError(null)
+    } catch (err) {
+      console.error('MDX compilation error:', err)
+      setError(err instanceof Error ? err : new Error(String(err)))
+      setCode(null)
+    } finally {
+      setIsCompiling(false)
+    }
+  }, [development])
+
+  useEffect(() => {
+    // Clear existing timeout
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current)
+    }
+
+    // Set up debounced compilation
+    timeoutRef.current = setTimeout(() => {
+      compileMDX(source)
+    }, debounceMs)
+
+    // Cleanup on unmount or source change
+    return () => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current)
+      }
+    }
+  }, [source, debounceMs, compileMDX])
+
+  return { code, error, isCompiling }
+}

package/src/site-preview/PayloadSiteField.tsx

@@ -0,0 +1,167 @@
+'use client'
+
+import { useField } from '@payloadcms/ui'
+import { SitePreview } from './SitePreview'
+
+export interface PayloadSiteFieldProps {
+  /**
+   * Optional additional components to merge with default site components
+   */
+  components?: Record<string, any>
+
+  /**
+   * Whether to show the preview panel (default: true)
+   */
+  showPreview?: boolean
+
+  /**
+   * Custom label for the preview section
+   */
+  previewLabel?: string
+
+  /**
+   * Debounce delay in milliseconds (default: 300ms)
+   */
+  debounceMs?: number
+
+  /**
+   * Position of preview panel: 'below' | 'side' (default: 'below')
+   */
+  previewPosition?: 'below' | 'side'
+}
+
+/**
+ * Payload CMS field component with live Site preview.
+ *
+ * This component integrates SitePreview with Payload's admin UI, providing
+ * a preview panel that shows real-time rendering of Site components as users
+ * edit MDX content.
+ *
+ * Features:
+ * - Automatically reads field value from Payload form state
+ * - Shows preview panel below or beside the input field
+ * - Supports all SiteComponents (Hero, Features, Pricing, etc.)
+ * - Debounced updates for smooth editing experience
+ * - Error handling with user-friendly messages
+ *
+ * @example
+ * ```tsx
+ * // In your Payload collection config:
+ * import { PayloadSiteField } from '@mdxui/payload/site-preview'
+ *
+ * {
+ *   name: 'content',
+ *   type: 'textarea',
+ *   admin: {
+ *     components: {
+ *       Field: PayloadSiteField,
+ *     },
+ *   },
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom configuration:
+ * {
+ *   name: 'heroSection',
+ *   type: 'textarea',
+ *   admin: {
+ *     components: {
+ *       Field: (props) => (
+ *         <PayloadSiteField
+ *           {...props}
+ *           previewLabel="Hero Preview"
+ *           debounceMs={500}
+ *         />
+ *       ),
+ *     },
+ *   },
+ * }
+ * ```
+ */
+export function PayloadSiteField(props: PayloadSiteFieldProps & { path: string }) {
+  const {
+    path,
+    components,
+    showPreview = true,
+    previewLabel = 'Live Preview',
+    debounceMs = 300,
+    previewPosition = 'below',
+  } = props
+
+  const { value } = useField<string>({ path })
+
+  // Don't render if preview is disabled or no content
+  if (!showPreview || !value) {
+    return null
+  }
+
+  const previewPanel = (
+    <div className="site-preview-panel rounded-lg border border-gray-200 bg-white shadow-sm overflow-hidden">
+      <div className="flex items-center justify-between border-b border-gray-200 bg-gray-50 px-4 py-2">
+        <h3 className="text-sm font-semibold text-gray-700">
+          {previewLabel}
+        </h3>
+        <div className="flex items-center gap-2">
+          <span className="inline-flex items-center rounded-full bg-green-100 px-2 py-1 text-xs font-medium text-green-700">
+            <span className="mr-1 h-1.5 w-1.5 rounded-full bg-green-600"></span>
+            Live
+          </span>
+        </div>
+      </div>
+      <div className="p-4 bg-white">
+        <SitePreview
+          content={value}
+          components={components}
+          debounceMs={debounceMs}
+        />
+      </div>
+    </div>
+  )
+
+  // Render based on position
+  if (previewPosition === 'side') {
+    return (
+      <div className="grid grid-cols-2 gap-4">
+        <div className="col-span-1">{previewPanel}</div>
+      </div>
+    )
+  }
+
+  // Default: below
+  return <div className="mt-4">{previewPanel}</div>
+}
+
+/**
+ * Factory function to create a PayloadSiteField component with preset configuration.
+ *
+ * Useful for creating consistent field components across multiple collections.
+ *
+ * @example
+ * ```tsx
+ * // Create a hero field component
+ * const HeroSiteField = createPayloadSiteField({
+ *   previewLabel: 'Hero Section Preview',
+ *   debounceMs: 500,
+ * })
+ *
+ * // Use in collection config:
+ * {
+ *   name: 'heroContent',
+ *   type: 'textarea',
+ *   admin: {
+ *     components: {
+ *       Field: HeroSiteField,
+ *     },
+ *   },
+ * }
+ * ```
+ */
+export function createPayloadSiteField(
+  defaultProps: Omit<PayloadSiteFieldProps, 'path'>
+) {
+  return function PayloadSiteFieldComponent(props: { path: string }) {
+    return <PayloadSiteField {...defaultProps} {...props} />
+  }
+}

package/src/site-preview/SitePreview.tsx

@@ -0,0 +1,194 @@
+'use client'
+
+import * as BeaconComponents from '@mdxui/beacon/components'
+import { MDXLiveRenderer } from 'mdxui'
+import { useMemo } from 'react'
+
+const { Hero, Features, Pricing, FAQs, Header, Footer, LandingLayout, Directory } = BeaconComponents
+
+/**
+ * Site components available for live preview
+ * These are the actual beacon implementations, not strictly typed to SiteComponents
+ * to allow for flexibility in MDX usage
+ */
+const siteComponents = {
+  Hero,
+  Features,
+  Pricing,
+  FAQ: FAQs,
+  FAQs,
+  Header,
+  Footer,
+  LandingLayout,
+  LandingPage: LandingLayout,
+  Directory,
+} as const
+
+export interface SitePreviewProps {
+  /**
+   * MDX content to preview
+   */
+  content: string
+
+  /**
+   * Optional additional components to merge with default site components
+   */
+  components?: Record<string, any>
+
+  /**
+   * Debounce delay in milliseconds (default: 300ms)
+   */
+  debounceMs?: number
+
+  /**
+   * Optional className for the preview wrapper
+   */
+  className?: string
+
+  /**
+   * Show loading indicator
+   */
+  showLoading?: boolean
+
+  /**
+   * Show error messages
+   */
+  showErrors?: boolean
+}
+
+/**
+ * Default loading component for SitePreview
+ */
+function SitePreviewLoading() {
+  return (
+    // biome-ignore lint/a11y/useSemanticElements: This is a loading indicator.
+    <div role='status' aria-live='polite' aria-label='Loading site preview' className='flex items-center justify-center p-8 text-gray-500'>
+      <div className='flex items-center gap-3'>
+        <div className='h-5 w-5 animate-spin rounded-full border-2 border-gray-300 border-t-gray-600' />
+        <span>Compiling preview...</span>
+      </div>
+    </div>
+  )
+}
+
+/**
+ * Default error component for SitePreview
+ */
+function SitePreviewError({ error }: { error: Error }) {
+  return (
+    <div role='alert' aria-live='assertive' className='m-4 rounded-md border border-red-300 bg-red-50 p-4'>
+      <div className='flex items-start gap-3'>
+        <svg className='h-5 w-5 flex-shrink-0 text-red-600' fill='currentColor' viewBox='0 0 20 20' aria-hidden='true'>
+          <path
+            fillRule='evenodd'
+            d='M10 18a8 8 0 100-16 8 8 0 000 16zM8.707 7.293a1 1 0 00-1.414 1.414L8.586 10l-1.293 1.293a1 1 0 101.414 1.414L10 11.414l1.293 1.293a1 1 0 001.414-1.414L11.414 10l1.293-1.293a1 1 0 00-1.414-1.414L10 8.586 8.707 7.293z'
+            clipRule='evenodd'
+          />
+        </svg>
+        <div className='flex-1'>
+          <h3 className='text-sm font-semibold text-red-800'>Preview Compilation Error</h3>
+          <pre className='mt-2 whitespace-pre-wrap break-words text-xs text-red-700'>{error.message}</pre>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+/**
+ * SitePreview - Live preview component for Site templates in Payload admin.
+ *
+ * This component uses the MDXLiveRenderer to provide real-time rendering of
+ * mdxui Site components (Hero, Features, Pricing, Blog, Docs, etc.) as users
+ * edit content in Payload CMS.
+ *
+ * Features:
+ * - Real-time MDX compilation and preview
+ * - Full SiteComponents support (Hero, Features, Pricing, FAQ, etc.)
+ * - Debounced updates for performance
+ * - Error handling with user-friendly messages
+ * - Loading states
+ * - Integrates seamlessly with Payload admin UI
+ *
+ * @example
+ * ```tsx
+ * // In a Payload collection field configuration:
+ * {
+ *   name: 'content',
+ *   type: 'textarea',
+ *   admin: {
+ *     components: {
+ *       Field: (props) => (
+ *         <div>
+ *           <TextareaField {...props} />
+ *           <SitePreview content={props.value} />
+ *         </div>
+ *       ),
+ *     },
+ *   },
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // As a standalone preview panel:
+ * <SitePreview
+ *   content={mdxContent}
+ *   debounceMs={500}
+ *   className="border rounded-lg"
+ * />
+ * ```
+ */
+export function SitePreview({
+  content,
+  components = {},
+  debounceMs = 300,
+  className = '',
+  showLoading = true,
+  showErrors = true,
+}: SitePreviewProps) {
+  // Merge provided components with default site components
+  const mergedComponents = useMemo(() => ({ ...siteComponents, ...components }), [components])
+
+  return (
+    <div className={`site-preview ${className}`}>
+      <MDXLiveRenderer
+        content={content}
+        components={mergedComponents as any}
+        debounceMs={debounceMs}
+        loadingComponent={showLoading ? <SitePreviewLoading /> : undefined}
+        errorComponent={showErrors ? SitePreviewError : undefined}
+      />
+    </div>
+  )
+}
+
+/**
+ * Factory function to create a SitePreview component with preset configuration.
+ *
+ * Useful for creating consistent preview components across multiple collections.
+ *
+ * @example
+ * ```tsx
+ * // Create a blog preview component
+ * const BlogPreview = createSitePreview({
+ *   debounceMs: 500,
+ *   className: 'blog-preview',
+ * })
+ *
+ * // Use in collection:
+ * {
+ *   name: 'content',
+ *   type: 'textarea',
+ *   admin: {
+ *     components: {
+ *       AfterInput: [BlogPreview],
+ *     },
+ *   },
+ * }
+ * ```
+ */
+export function createSitePreview(defaultProps: Partial<Omit<SitePreviewProps, 'content'>>) {
+  return function SitePreviewComponent({ content }: { content: string }) {
+    return <SitePreview content={content} {...defaultProps} />
+  }
+}

package/src/site-preview/index.ts

@@ -0,0 +1,31 @@
+/**
+ * SitePreview - Live preview for Site templates in Payload admin
+ *
+ * This module provides real-time MDX preview components for Site content,
+ * using the MDXLiveRenderer with SiteComponents from @mdxui/beacon.
+ *
+ * @example
+ * ```tsx
+ * import { SitePreview, PayloadSiteField } from '@mdxui/payload/site-preview'
+ *
+ * // As a standalone preview:
+ * <SitePreview content={mdxContent} />
+ *
+ * // As a Payload field component:
+ * {
+ *   name: 'content',
+ *   type: 'textarea',
+ *   admin: {
+ *     components: {
+ *       Field: PayloadSiteField,
+ *     },
+ *   },
+ * }
+ * ```
+ */
+
+export { SitePreview, createSitePreview } from './SitePreview'
+export type { SitePreviewProps } from './SitePreview'
+
+export { PayloadSiteField, createPayloadSiteField } from './PayloadSiteField'
+export type { PayloadSiteFieldProps } from './PayloadSiteField'

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "@mdxui/typescript-config/react-library.json",
+  "include": ["."],
+  "exclude": ["dist", "build", "node_modules"]
+}