@blogmcp/mdx-render-react 0.1.0

package/src/render/gallery/GalleryLightbox.tsx

@@ -0,0 +1,201 @@
+'use client'
+
+import { useCallback, useEffect, useRef, type TouchEvent as ReactTouchEvent, type MouseEvent as ReactMouseEvent } from 'react'
+import { createPortal } from 'react-dom'
+
+export interface GalleryLightboxProps {
+  isOpen: boolean
+  currentIndex: number
+  imageCount: number
+  getImageSrc: (index: number) => string
+  getImageAlt: (index: number) => string
+  getImageDescription: (index: number) => string | undefined
+  onClose: () => void
+  onNavigate: (index: number) => void
+}
+
+/**
+ * Fullscreen image viewer with keyboard + touch navigation. Client island —
+ * mirrors Vue GalleryLightbox.vue: portalled to <body>, dark backdrop,
+ * close/prev/next buttons, image counter, Escape + ArrowLeft/Right keys,
+ * click-backdrop-to-close, and horizontal-swipe navigation. Markup, classes,
+ * and `aria-label`s match the Vue source.
+ */
+export default function GalleryLightbox({
+  isOpen,
+  currentIndex,
+  imageCount,
+  getImageSrc,
+  getImageAlt,
+  getImageDescription,
+  onClose,
+  onNavigate,
+}: GalleryLightboxProps) {
+  const hasPrev = currentIndex > 0
+  const hasNext = currentIndex < imageCount - 1
+  const showNav = imageCount > 1
+
+  // Keyboard navigation — registered while open, mirrors Vue's document listener.
+  useEffect(() => {
+    if (!isOpen) return
+    function onKeydown(e: KeyboardEvent) {
+      if (e.key === 'Escape') {
+        onClose()
+      } else if (e.key === 'ArrowLeft' && currentIndex > 0) {
+        onNavigate(currentIndex - 1)
+      } else if (e.key === 'ArrowRight' && currentIndex < imageCount - 1) {
+        onNavigate(currentIndex + 1)
+      }
+    }
+    document.addEventListener('keydown', onKeydown)
+    return () => document.removeEventListener('keydown', onKeydown)
+  }, [isOpen, currentIndex, imageCount, onClose, onNavigate])
+
+  // Scroll lock while the lightbox is open (mirrors Vue's body overflow watch).
+  useEffect(() => {
+    if (!isOpen) return
+    document.body.style.overflow = 'hidden'
+    return () => {
+      document.body.style.overflow = ''
+    }
+  }, [isOpen])
+
+  // Touch swipe.
+  const touchStartX = useRef(0)
+  const touchStartY = useRef(0)
+
+  const onTouchStart = useCallback((e: ReactTouchEvent) => {
+    touchStartX.current = e.touches[0].clientX
+    touchStartY.current = e.touches[0].clientY
+  }, [])
+
+  const onTouchEnd = useCallback(
+    (e: ReactTouchEvent) => {
+      const dx = e.changedTouches[0].clientX - touchStartX.current
+      const dy = e.changedTouches[0].clientY - touchStartY.current
+      if (Math.abs(dx) > 50 && Math.abs(dx) > Math.abs(dy)) {
+        if (dx < 0 && hasNext) {
+          onNavigate(currentIndex + 1)
+        } else if (dx > 0 && hasPrev) {
+          onNavigate(currentIndex - 1)
+        }
+      }
+    },
+    [currentIndex, hasNext, hasPrev, onNavigate],
+  )
+
+  const onBackdropClick = useCallback(
+    (e: ReactMouseEvent) => {
+      if (e.target === e.currentTarget) {
+        onClose()
+      }
+    },
+    [onClose],
+  )
+
+  if (!isOpen || typeof document === 'undefined') return null
+
+  const description = getImageDescription(currentIndex)
+
+  return createPortal(
+    <div
+      className="lightbox-overlay fixed inset-0 z-50 flex items-center justify-center bg-black/90"
+      role="dialog"
+      aria-modal="true"
+      onClick={onBackdropClick}
+      onTouchStart={onTouchStart}
+      onTouchEnd={onTouchEnd}
+    >
+      {/* Close button */}
+      <button
+        type="button"
+        className="lightbox-close absolute top-4 right-4 z-10 text-white/80 hover:text-white p-2"
+        aria-label="Close lightbox"
+        onClick={onClose}
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="28"
+          height="28"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth={2}
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        >
+          <line x1="18" y1="6" x2="6" y2="18" />
+          <line x1="6" y1="6" x2="18" y2="18" />
+        </svg>
+      </button>
+
+      {/* Image counter */}
+      {showNav ? (
+        <div className="lightbox-counter absolute top-4 left-4 text-white/80 text-sm select-none">
+          {currentIndex + 1} / {imageCount}
+        </div>
+      ) : null}
+
+      {/* Previous button */}
+      {showNav && hasPrev ? (
+        <button
+          type="button"
+          className="lightbox-prev absolute left-4 top-1/2 -translate-y-1/2 z-10 text-white/80 hover:text-white p-2"
+          aria-label="Previous image"
+          onClick={() => onNavigate(currentIndex - 1)}
+        >
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="32"
+            height="32"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth={2}
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          >
+            <polyline points="15 18 9 12 15 6" />
+          </svg>
+        </button>
+      ) : null}
+
+      {/* Next button */}
+      {showNav && hasNext ? (
+        <button
+          type="button"
+          className="lightbox-next absolute right-4 top-1/2 -translate-y-1/2 z-10 text-white/80 hover:text-white p-2"
+          aria-label="Next image"
+          onClick={() => onNavigate(currentIndex + 1)}
+        >
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="32"
+            height="32"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth={2}
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          >
+            <polyline points="9 18 15 12 9 6" />
+          </svg>
+        </button>
+      ) : null}
+
+      {/* Image + caption */}
+      <div className="flex flex-col items-center max-h-[95vh] max-w-[90vw]" onClick={(e) => e.stopPropagation()}>
+        <img
+          src={getImageSrc(currentIndex)}
+          alt={getImageAlt(currentIndex)}
+          className="lightbox-image max-h-[85vh] max-w-[90vw] object-contain"
+        />
+        {description ? (
+          <p className="lightbox-caption text-white/80 text-sm mt-3 text-center max-w-[80vw]">{description}</p>
+        ) : null}
+      </div>
+    </div>,
+    document.body,
+  )
+}

package/src/render/gallery/gallery.ts

@@ -0,0 +1,90 @@
+/**
+ * Gallery helpers — mirrored from
+ * `@blogmcp/mdx-render-vue/src/composables/useGallery.ts`.
+ */
+import type { CSSProperties } from 'react'
+import { galleryTileLayout as sharedGalleryTileLayout } from '@blogmcp/mdx-schema/styles'
+import type { GalleryImage, GalleryProps, MediaObject } from '@blogmcp/mdx-schema'
+
+const VIDEO_EXTENSIONS = /\.(mp4|webm|mov|avi|mkv|m4v)(\?.*)?$/i
+const KB_MEDIA_FILE_RE = /\/api\/media\/file\/([^/?#]+)/
+
+export const gridColsClasses: Record<number, string> = {
+  1: 'grid-cols-1',
+  2: 'grid-cols-2',
+  3: 'grid-cols-3',
+  4: 'grid-cols-4',
+}
+
+export function isMediaObject(value: unknown): value is MediaObject {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'src' in value &&
+    typeof (value as MediaObject).src === 'string'
+  )
+}
+
+export function isVideoUrl(src: string): boolean {
+  return VIDEO_EXTENSIONS.test(src)
+}
+
+export function gridColsClass(columns?: number): string {
+  return gridColsClasses[columns || 2] || 'grid-cols-2'
+}
+
+export function gapClass(gap?: number): string {
+  return `gap-${gap || 4}`
+}
+
+/**
+ * React-typed adapter over the shared, framework-agnostic `galleryTileLayout`
+ * in `@blogmcp/mdx-schema/styles` (the single source of truth for tile
+ * geometry — keeps the Vue + React flavors byte-identical). The shared helper
+ * returns `Record<string,string>`; the values are valid CSS, so casting to
+ * React's `CSSProperties` for the `style` prop is safe.
+ */
+export interface GalleryTileLayout {
+  tileStyle: CSSProperties
+  mediaStyle: CSSProperties
+  mediaSizeClass: string
+}
+
+export function galleryTileLayout(
+  props: Pick<GalleryProps, 'aspectRatio' | 'fit' | 'position'>,
+): GalleryTileLayout {
+  const layout = sharedGalleryTileLayout(props)
+  return {
+    tileStyle: layout.tileStyle as CSSProperties,
+    mediaStyle: layout.mediaStyle as CSSProperties,
+    mediaSizeClass: layout.mediaSizeClass,
+  }
+}
+
+export function getImageSrc(image: GalleryImage): string {
+  return isMediaObject(image) ? image.src : image
+}
+
+export function getImageAlt(image: GalleryImage, index: number): string {
+  if (isMediaObject(image)) return image.alt || `Gallery image ${index + 1}`
+  return `Gallery image ${index + 1}`
+}
+
+export function getImageDescription(image: GalleryImage): string | undefined {
+  return isMediaObject(image) ? image.description : undefined
+}
+
+export function isVideo(image: GalleryImage): boolean {
+  if (isMediaObject(image)) {
+    if (image.type === 'video') return true
+    if (image.type === 'image') return false
+    return isVideoUrl(image.src)
+  }
+  return isVideoUrl(image)
+}
+
+export function getVideoPoster(image: GalleryImage): string | undefined {
+  const src = getImageSrc(image)
+  const match = src.match(KB_MEDIA_FILE_RE)
+  return match ? `/api/media/poster/${match[1]}` : undefined
+}

package/src/render/icon/Icon.tsx

@@ -0,0 +1,25 @@
+import { Icon as IconifyIcon } from '@iconify/react'
+
+export interface IconProps {
+  name: string
+  size?: number
+  color?: string
+}
+
+/**
+ * Inline Iconify icon (any set). Mirrors Vue Icon.vue — the
+ * data-mdx-component attribute lands on the rendered <svg> via Iconify's
+ * attribute pass-through.
+ */
+export default function Icon({ name, size = 20, color }: IconProps) {
+  return (
+    <IconifyIcon
+      icon={name}
+      width={size}
+      height={size}
+      style={color ? { color } : undefined}
+      className="inline-block align-[-0.125em]"
+      data-mdx-component="Icon"
+    />
+  )
+}

package/src/render/index.ts

@@ -0,0 +1,26 @@
+/**
+ * React MDX render components.
+ *
+ * Named exports for every render component. The two client islands (Tooltip,
+ * AudioPlayerDefault) carry their own `'use client'` banner.
+ */
+export { default as CalloutDefault } from './callout/CalloutDefault'
+export { default as CalloutMinimal } from './callout/CalloutMinimal'
+export { default as YouTubeDefault } from './youtube/YouTubeDefault'
+export { default as GalleryGrid } from './gallery/GalleryGrid'
+export { default as CodeBlockDefault } from './codeblock/CodeBlockDefault'
+export { default as AudioPlayerDefault } from './audioplayer/AudioPlayerDefault'
+export { default as Button } from './button/Button'
+export { default as Card } from './card/Card'
+export { default as Alert } from './alert/Alert'
+export { default as Badge } from './badge/Badge'
+export { default as Icon } from './icon/Icon'
+export { default as Tooltip } from './tooltip/Tooltip'
+
+export type { ButtonProps } from './button/Button'
+export type { BadgeProps } from './badge/Badge'
+export type { AlertProps } from './alert/Alert'
+export type { CardProps } from './card/Card'
+export type { IconProps } from './icon/Icon'
+export type { TooltipProps } from './tooltip/Tooltip'
+export type { CalloutProps } from './callout/CalloutDefault'

package/src/render/tooltip/Tooltip.tsx

@@ -0,0 +1,38 @@
+'use client'
+
+import type { ReactNode } from 'react'
+import { Tooltip as ArkTooltip, Portal } from '@ark-ui/react'
+
+export interface TooltipProps {
+  label: string
+  placement?: 'top' | 'bottom' | 'left' | 'right'
+  children?: ReactNode
+}
+
+/**
+ * Hover-reveal tooltip backed by Ark UI (React). Client island — mirrors Vue
+ * Tooltip.vue: same Ark namespaced primitive, same delays/positioning, same
+ * content classes, portalled content. The trigger wraps an inline span that
+ * carries `data-mdx-component="Tooltip"`.
+ */
+export default function Tooltip({ label, placement = 'top', children }: TooltipProps) {
+  return (
+    <ArkTooltip.Root positioning={{ placement }} openDelay={200} closeDelay={100}>
+      <ArkTooltip.Trigger asChild>
+        <span className="inline-flex" data-mdx-component="Tooltip">
+          {children}
+        </span>
+      </ArkTooltip.Trigger>
+      <Portal>
+        <ArkTooltip.Positioner>
+          <ArkTooltip.Content className="z-50 rounded-md bg-gray-900 px-2.5 py-1.5 text-xs text-white shadow-lg data-[state=open]:animate-in data-[state=closed]:animate-out">
+            <ArkTooltip.Arrow>
+              <ArkTooltip.ArrowTip className="border-gray-900" />
+            </ArkTooltip.Arrow>
+            {label}
+          </ArkTooltip.Content>
+        </ArkTooltip.Positioner>
+      </Portal>
+    </ArkTooltip.Root>
+  )
+}

package/src/render/youtube/YouTubeDefault.tsx

@@ -0,0 +1,58 @@
+'use client'
+
+import { useState } from 'react'
+import type { YouTubeProps } from '@blogmcp/mdx-schema'
+import { embedUrl, thumbnailUrl, YOUTUBE_IFRAME_ALLOW } from './youtube'
+
+/**
+ * YouTube facade. Client island — mirrors Vue YouTubeDefault.vue + useYouTube.ts.
+ *
+ * Facade pattern: renders a thumbnail + play-button overlay initially (the
+ * server/initial DOM), and swaps to the real autoplay iframe on click — saving
+ * ~500KB per embed until the user actually plays. The `youtube-embed` wrapper,
+ * `data-mdx-component="YouTube"`, and the 56.25% aspect-ratio box are identical
+ * to the static/Vue versions; the interactive bit lives inside the box.
+ */
+export default function YouTubeDefault({ id, title }: YouTubeProps) {
+  const iframeTitle = title || 'YouTube video'
+  const thumb = thumbnailUrl(id)
+  const [activated, setActivated] = useState(false)
+
+  return (
+    <div className="youtube-embed my-6" data-mdx-component="YouTube" data-allow={YOUTUBE_IFRAME_ALLOW}>
+      <div className="relative w-full rounded-lg overflow-hidden shadow-md" style={{ paddingBottom: '56.25%' }}>
+        {!activated ? (
+          <button
+            type="button"
+            className="absolute inset-0 w-full h-full cursor-pointer border-0 p-0 bg-black group"
+            aria-label={`Play ${iframeTitle}`}
+            onClick={() => setActivated(true)}
+          >
+            <img src={thumb} alt={iframeTitle} className="absolute inset-0 w-full h-full object-cover" />
+            <svg
+              className="absolute inset-0 m-auto w-16 h-16 text-white drop-shadow-lg opacity-90 group-hover:opacity-100 transition-opacity"
+              viewBox="0 0 68 48"
+              aria-hidden="true"
+            >
+              <path
+                d="M66.52 7.74c-.78-2.93-2.49-5.41-5.42-6.19C55.79.13 34 0 34 0S12.21.13 6.9 1.55C3.97 2.33 2.27 4.81 1.48 7.74.06 13.05 0 24 0 24s.06 10.95 1.48 16.26c.78 2.93 2.49 5.41 5.42 6.19C12.21 47.87 34 48 34 48s21.79-.13 27.1-1.55c2.93-.78 4.64-3.26 5.42-6.19C67.94 34.95 68 24 68 24s-.06-10.95-1.48-16.26z"
+                fill="red"
+              />
+              <path d="M45 24L27 14v20" fill="white" />
+            </svg>
+          </button>
+        ) : (
+          <iframe
+            src={`${embedUrl(id)}?autoplay=1`}
+            title={iframeTitle}
+            className="absolute inset-0 w-full h-full"
+            frameBorder="0"
+            allow={YOUTUBE_IFRAME_ALLOW}
+            allowFullScreen
+          />
+        )}
+      </div>
+      {title ? <p className="text-center text-sm text-gray-600 mt-3">{title}</p> : null}
+    </div>
+  )
+}

package/src/render/youtube/youtube.ts

@@ -0,0 +1,17 @@
+/**
+ * YouTube URL helpers — mirrored from
+ * `@blogmcp/mdx-render-vue/src/composables/useYouTube.ts`.
+ */
+export const YOUTUBE_EMBED_BASE = 'https://www.youtube.com/embed/'
+
+export const YOUTUBE_IFRAME_ALLOW =
+  'accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture'
+
+export function embedUrl(id: string): string {
+  return `${YOUTUBE_EMBED_BASE}${id}`
+}
+
+export function thumbnailUrl(id: string): string {
+  if (!id) return ''
+  return `https://img.youtube.com/vi/${id}/maxresdefault.jpg`
+}

package/src/server-render-map.ts

@@ -0,0 +1,120 @@
+/**
+ * Static render map used by MdxContent.
+ *
+ * Direct (non-lazy) imports of every render component, keyed by the schema's
+ * PascalCase component name. The two client islands (Tooltip, AudioPlayer)
+ * are referenced here too — a Next.js consumer ships them as islands because
+ * each carries its own `'use client'` banner.
+ *
+ * `default` variants only; the registry (registry.ts) carries the full
+ * variant map (e.g. Callout `minimal`) for future tooling.
+ *
+ * Two maps are exported:
+ *
+ * - `serverRenderMap` — raw components. Kept as an escape hatch for
+ *   tooling that needs the bare component reference (snapshot fixtures,
+ *   manual instantiation in tests). PRODUCTION CODE SHOULD NOT USE IT.
+ *
+ * - `wrappedServerRenderMap` — `prepareProps`-aware components. Each
+ *   entry is the raw component wrapped in a tiny HOC that runs every
+ *   incoming prop through `prepareProps(props, metadata)` before
+ *   forwarding to the real component. This makes the schema's render-
+ *   time shim impossible to forget at call sites: any consumer doing
+ *   `<Comp {...item.props}>` gets normalized props automatically,
+ *   including for recursively-rendered nested MDX children.
+ */
+import { createElement, type ComponentType, type ReactNode } from 'react'
+import {
+  componentMetadata,
+  prepareProps,
+  type ComponentMetadata,
+} from '@blogmcp/mdx-schema'
+
+import CalloutDefault from './render/callout/CalloutDefault'
+import YouTubeDefault from './render/youtube/YouTubeDefault'
+import GalleryGrid from './render/gallery/GalleryGrid'
+import CodeBlockDefault from './render/codeblock/CodeBlockDefault'
+import AudioPlayerDefault from './render/audioplayer/AudioPlayerDefault'
+import Button from './render/button/Button'
+import Card from './render/card/Card'
+import Alert from './render/alert/Alert'
+import Badge from './render/badge/Badge'
+import Icon from './render/icon/Icon'
+import Tooltip from './render/tooltip/Tooltip'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const serverRenderMap: Record<string, ComponentType<any>> = {
+  Callout: CalloutDefault,
+  YouTube: YouTubeDefault,
+  Gallery: GalleryGrid,
+  CodeBlock: CodeBlockDefault,
+  AudioPlayer: AudioPlayerDefault,
+  Button,
+  Card,
+  Alert,
+  Badge,
+  Icon,
+  Tooltip,
+}
+
+/**
+ * Sentinel property name read by the per-renderer "prepareProps is
+ * wired" integration test. Wrapped components carry this with the
+ * component's schema name so the test can confirm wrapping end-to-end
+ * (vs the historical regex-grep on registry source, which was easily
+ * defeated by commented-out code and unused imports).
+ */
+export const MDX_PREPARED_SENTINEL = '__mdxPreparePropsAppliedFor' as const
+
+/**
+ * HOC that wraps a render component so every invocation runs incoming
+ * props through `prepareProps(props, metadata)` before forwarding to
+ * the inner component. Re-rendered components from nested MDX go
+ * through the same wrapped reference, so recursion does not bypass
+ * the shim.
+ *
+ * Children are forwarded untouched — `prepareProps` operates on the
+ * named props only; the `children` slot is a structural concern.
+ *
+ * The wrapper sets a `displayName` for React DevTools and stamps the
+ * `MDX_PREPARED_SENTINEL` property so the CI integration test can
+ * confirm the wrapper was applied.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function wrapReactComponentForMdx<P extends Record<string, any>>(
+  Inner: ComponentType<P>,
+  metadata: ComponentMetadata,
+): ComponentType<P & { children?: ReactNode }> {
+  const Wrapped = function MdxPrepared(props: P & { children?: ReactNode }) {
+    const { children, ...rest } = props as P & { children?: ReactNode }
+    const normalized = prepareProps(rest as Record<string, unknown>, metadata) as P
+    return createElement(Inner, normalized, children)
+  }
+  ;(Wrapped as unknown as Record<string, unknown>)[MDX_PREPARED_SENTINEL] = metadata.name
+  Wrapped.displayName = `MdxPrepared(${metadata.name})`
+  return Wrapped as ComponentType<P & { children?: ReactNode }>
+}
+
+const metadataByName: Map<string, ComponentMetadata> = new Map(
+  componentMetadata.map(m => [m.name, m]),
+)
+
+function getMetadataOrThrow(name: string): ComponentMetadata {
+  const m = metadataByName.get(name)
+  if (!m) {
+    throw new Error(
+      `[mdx-render-react] No componentMetadata for "${name}" — the React render map ` +
+      `has a component the schema does not know about. Add an entry in ` +
+      `packages/mdx-schema/src/metadata/index.ts or remove the entry from serverRenderMap.`,
+    )
+  }
+  return m
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const wrappedServerRenderMap: Record<string, ComponentType<any>> = Object.fromEntries(
+  Object.entries(serverRenderMap).map(([name, Inner]) => [
+    name,
+    wrapReactComponentForMdx(Inner, getMetadataOrThrow(name)),
+  ]),
+)