prev-cli 0.24.18 → 0.24.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prev-cli",
-  "version": "0.24.18",
+  "version": "0.24.19",
   "description": "Transform MDX directories into beautiful documentation websites",
   "type": "module",
   "license": "MIT",
@@ -11,7 +11,10 @@
     "dist",
     "src/theme",
     "src/ui",
-    "src/preview-runtime"
+    "src/preview-runtime",
+    "src/jsx",
+    "src/primitives",
+    "src/tokens"
   ],
   "keywords": [
     "documentation",

package/src/jsx/adapters/html.test.ts

@@ -0,0 +1,191 @@
+// src/jsx/adapters/html.test.ts
+import { test, expect, describe, beforeEach } from 'bun:test'
+import { resetIdCounter } from '../vnode'
+import { Col, Row, Box, Spacer, Slot, Text, Icon, Image } from '../jsx-runtime'
+import { renderToHtml, setTokensConfig } from './html'
+import { resolveTokens } from '../../tokens/resolver'
+
+// Get default tokens once at module load for test stability
+const defaultTokens = resolveTokens({})
+
+beforeEach(() => {
+  resetIdCounter()
+  // Explicitly set default tokens for test isolation
+  setTokensConfig(defaultTokens)
+})
+
+describe('renderToHtml', () => {
+  test('primitives, escaping, slots, nesting', () => {
+    expect(renderToHtml(Col({ gap: 'lg' }))).toContain('gap-6')
+    expect(renderToHtml(Row({ align: 'between' }))).toContain('justify-between')
+    expect(renderToHtml(Box({ bg: 'muted' }))).toContain('bg-muted')
+    expect(renderToHtml(Spacer())).toContain('flex-1')
+    expect(renderToHtml(Text({ children: '<script>', weight: 'bold' }))).toContain('&lt;script&gt;')
+    expect(renderToHtml(Icon({ name: 'star', color: 'primary' }))).toContain('text-primary')
+    expect(renderToHtml(Image({ src: '"><x>', fit: 'cover' }))).toContain('&quot;&gt;')
+
+    const html = renderToHtml(Slot({ name: 'x' }), { state: 'on', slots: { x: { on: Text({ children: 'On' }) } } })
+    expect(html).toContain('On')
+
+    expect(renderToHtml(Col({ children: [Text({ children: 'Hi' })] }))).toContain('data-node-id=')
+  })
+})
+
+describe('HTML adapter token mapping', () => {
+  beforeEach(() => {
+    setTokensConfig(defaultTokens)
+  })
+
+  test('Box maps bg token to Tailwind class', () => {
+    const node = {
+      type: 'box' as const,
+      id: 'test-1',
+      props: { bg: 'primary' },
+      children: []
+    }
+    const html = renderToHtml(node)
+    expect(html).toContain('bg-primary')
+  })
+
+  test('Box maps padding token to Tailwind class', () => {
+    const node = {
+      type: 'box' as const,
+      id: 'test-2',
+      props: { padding: 'lg' },
+      children: []
+    }
+    const html = renderToHtml(node)
+    expect(html).toContain('p-6')
+  })
+
+  test('Text maps color token to Tailwind class', () => {
+    const node = {
+      type: 'text' as const,
+      id: 'test-3',
+      props: { content: 'hi', color: 'muted-foreground' },
+      children: []
+    }
+    const html = renderToHtml(node)
+    expect(html).toContain('text-muted-foreground')
+  })
+
+  test('Text maps size token to Tailwind class', () => {
+    const node = {
+      type: 'text' as const,
+      id: 'test-4',
+      props: { content: 'hi', size: 'lg' },
+      children: []
+    }
+    const html = renderToHtml(node)
+    expect(html).toContain('text-lg')
+  })
+
+  test('Text maps weight token to Tailwind class', () => {
+    const node = {
+      type: 'text' as const,
+      id: 'test-5',
+      props: { content: 'hi', weight: 'bold' },
+      children: []
+    }
+    const html = renderToHtml(node)
+    expect(html).toContain('font-bold')
+  })
+
+  test('Row maps gap token to Tailwind class', () => {
+    const node = {
+      type: 'row' as const,
+      id: 'test-6',
+      props: { gap: 'md' },
+      children: []
+    }
+    const html = renderToHtml(node)
+    expect(html).toContain('gap-4')
+  })
+
+  test('Box maps radius token to Tailwind class', () => {
+    const node = {
+      type: 'box' as const,
+      id: 'test-7',
+      props: { radius: 'lg' },
+      children: []
+    }
+    const html = renderToHtml(node)
+    expect(html).toContain('rounded-lg')
+  })
+
+  test('throws error for missing background token', () => {
+    const incompleteTokens = {
+      ...defaultTokens,
+      backgrounds: { ...defaultTokens.backgrounds }
+    }
+    delete (incompleteTokens.backgrounds as Record<string, unknown>)['primary']
+
+    setTokensConfig(incompleteTokens as any)
+
+    const node = {
+      type: 'box' as const,
+      id: 'test-missing-bg',
+      props: { bg: 'primary' },
+      children: []
+    }
+
+    expect(() => renderToHtml(node)).toThrow(/Missing background token: "primary"/)
+  })
+
+  test('throws error for missing spacing token', () => {
+    const incompleteTokens = {
+      ...defaultTokens,
+      spacing: { ...defaultTokens.spacing }
+    }
+    delete (incompleteTokens.spacing as Record<string, unknown>)['lg']
+
+    setTokensConfig(incompleteTokens as any)
+
+    const node = {
+      type: 'col' as const,
+      id: 'test-missing-spacing',
+      props: { gap: 'lg' },
+      children: []
+    }
+
+    expect(() => renderToHtml(node)).toThrow(/Missing spacing token: "lg"/)
+  })
+
+  test('throws error for missing color token', () => {
+    const incompleteTokens = {
+      ...defaultTokens,
+      colors: { ...defaultTokens.colors }
+    }
+    delete (incompleteTokens.colors as Record<string, unknown>)['primary']
+
+    setTokensConfig(incompleteTokens as any)
+
+    const node = {
+      type: 'text' as const,
+      id: 'test-missing-color',
+      props: { content: 'hi', color: 'primary' },
+      children: []
+    }
+
+    expect(() => renderToHtml(node)).toThrow(/Missing color token: "primary"/)
+  })
+
+  test('throws error for missing radius token', () => {
+    const incompleteTokens = {
+      ...defaultTokens,
+      radius: { ...defaultTokens.radius }
+    }
+    delete (incompleteTokens.radius as Record<string, unknown>)['lg']
+
+    setTokensConfig(incompleteTokens as any)
+
+    const node = {
+      type: 'box' as const,
+      id: 'test-missing-radius',
+      props: { radius: 'lg' },
+      children: []
+    }
+
+    expect(() => renderToHtml(node)).toThrow(/Missing radius token: "lg"/)
+  })
+})

package/src/jsx/adapters/html.ts

@@ -0,0 +1,404 @@
+// src/jsx/adapters/html.ts
+// HTML adapter - renders VNode tree to HTML with Tailwind classes
+import type { VNodeType } from '../vnode'
+import type {
+  SpacingToken,
+  AlignToken,
+  BackgroundToken,
+  RadiusToken,
+  ColorToken,
+  SizeToken,
+  WeightToken,
+  FitToken,
+} from '../schemas/tokens'
+import { resolveTokens, type TokensConfig } from '../../tokens/resolver'
+
+// ============================================================
+// Token resolution with caching for validation
+// ============================================================
+
+// Cached tokens - resolved once and reused
+let cachedTokens: TokensConfig | null = null
+
+// NOTE: getTokens() is called multiple times throughout the rendering process.
+// This is acceptable because:
+// - The first call caches the tokens in cachedTokens
+// - Subsequent calls just check `if (!cachedTokens)` which is O(1)
+// - For a CLI preview tool, this micro-optimization is not worth the complexity
+//   of threading tokens through every function
+function getTokens(): TokensConfig {
+  if (!cachedTokens) {
+    cachedTokens = resolveTokens({})
+  }
+  return cachedTokens
+}
+
+// Allow setting custom tokens (for testing and runtime override)
+export function setTokensConfig(tokens: TokensConfig | undefined): void {
+  cachedTokens = tokens || null
+}
+
+// Validation helpers - check token exists, then let Tailwind handle the actual value
+function validateSpacing(token: SpacingToken): void {
+  if (getTokens().spacing[token] === undefined) {
+    throw new Error(`Missing spacing token: "${token}". Check your tokens.yaml configuration.`)
+  }
+}
+
+function validateBackground(token: BackgroundToken): void {
+  if (getTokens().backgrounds[token] === undefined) {
+    throw new Error(`Missing background token: "${token}". Check your tokens.yaml configuration.`)
+  }
+}
+
+function validateRadius(token: RadiusToken): void {
+  if (getTokens().radius[token] === undefined) {
+    throw new Error(`Missing radius token: "${token}". Check your tokens.yaml configuration.`)
+  }
+}
+
+function validateColor(token: ColorToken): void {
+  if (getTokens().colors[token] === undefined) {
+    throw new Error(`Missing color token: "${token}". Check your tokens.yaml configuration.`)
+  }
+}
+
+function validateTypographySize(token: SizeToken): void {
+  if (getTokens().typography.sizes[token] === undefined) {
+    throw new Error(`Missing typography.sizes token: "${token}". Check your tokens.yaml configuration.`)
+  }
+}
+
+function validateTypographyWeight(token: WeightToken): void {
+  if (getTokens().typography.weights[token] === undefined) {
+    throw new Error(`Missing typography.weights token: "${token}". Check your tokens.yaml configuration.`)
+  }
+}
+
+// ============================================================
+// Token to Tailwind class mappings (shadcn-compatible)
+// ============================================================
+
+const SPACING_GAP: Record<SpacingToken, string> = {
+  none: 'gap-0',
+  xs: 'gap-1',
+  sm: 'gap-2',
+  md: 'gap-4',
+  lg: 'gap-6',
+  xl: 'gap-8',
+  '2xl': 'gap-12',
+}
+
+const SPACING_PADDING: Record<SpacingToken, string> = {
+  none: 'p-0',
+  xs: 'p-1',
+  sm: 'p-2',
+  md: 'p-4',
+  lg: 'p-6',
+  xl: 'p-8',
+  '2xl': 'p-12',
+}
+
+const SPACING_SIZE: Record<SpacingToken, string> = {
+  none: 'w-0 h-0',
+  xs: 'w-1 h-1',
+  sm: 'w-2 h-2',
+  md: 'w-4 h-4',
+  lg: 'w-6 h-6',
+  xl: 'w-8 h-8',
+  '2xl': 'w-12 h-12',
+}
+
+const ALIGN_ITEMS: Record<AlignToken, string> = {
+  start: 'items-start',
+  center: 'items-center',
+  end: 'items-end',
+  stretch: 'items-stretch',
+  between: 'justify-between',
+}
+
+const BG_CLASS: Record<BackgroundToken, string> = {
+  transparent: 'bg-transparent',
+  background: 'bg-background',
+  card: 'bg-card',
+  primary: 'bg-primary',
+  secondary: 'bg-secondary',
+  muted: 'bg-muted',
+  accent: 'bg-accent',
+  destructive: 'bg-destructive',
+  input: 'bg-input',
+}
+
+const RADIUS_CLASS: Record<RadiusToken, string> = {
+  none: 'rounded-none',
+  sm: 'rounded-sm',
+  md: 'rounded-md',
+  lg: 'rounded-lg',
+  xl: 'rounded-xl',
+  full: 'rounded-full',
+}
+
+const COLOR_CLASS: Record<ColorToken, string> = {
+  foreground: 'text-foreground',
+  'card-foreground': 'text-card-foreground',
+  primary: 'text-primary',
+  'primary-foreground': 'text-primary-foreground',
+  secondary: 'text-secondary',
+  'secondary-foreground': 'text-secondary-foreground',
+  muted: 'text-muted',
+  'muted-foreground': 'text-muted-foreground',
+  accent: 'text-accent',
+  'accent-foreground': 'text-accent-foreground',
+  destructive: 'text-destructive',
+  'destructive-foreground': 'text-destructive-foreground',
+  border: 'text-border',
+  ring: 'text-ring',
+}
+
+const SIZE_CLASS: Record<SizeToken, string> = {
+  xs: 'text-xs',
+  sm: 'text-sm',
+  base: 'text-base',
+  lg: 'text-lg',
+  xl: 'text-xl',
+  '2xl': 'text-2xl',
+}
+
+const ICON_SIZE_CLASS: Record<SizeToken, string> = {
+  xs: 'w-3 h-3',
+  sm: 'w-4 h-4',
+  base: 'w-5 h-5',
+  lg: 'w-6 h-6',
+  xl: 'w-7 h-7',
+  '2xl': 'w-8 h-8',
+}
+
+const WEIGHT_CLASS: Record<WeightToken, string> = {
+  normal: 'font-normal',
+  medium: 'font-medium',
+  semibold: 'font-semibold',
+  bold: 'font-bold',
+}
+
+const FIT_CLASS: Record<FitToken, string> = {
+  cover: 'object-cover',
+  contain: 'object-contain',
+  fill: 'object-fill',
+}
+
+// ============================================================
+// Render context
+// ============================================================
+
+export interface RenderContext {
+  /** Current state for slot resolution */
+  state?: string
+  /** Slots mapping: slotName -> stateName -> VNode */
+  slots?: Record<string, Record<string, VNodeType>>
+  /** Callback to render component nodes */
+  renderComponent?: (name: string, props: Record<string, unknown>, children?: VNodeType[]) => string
+}
+
+// ============================================================
+// Main render function
+// ============================================================
+
+/**
+ * Render a VNode tree to HTML
+ */
+export function renderToHtml(node: VNodeType, context: RenderContext = {}): string {
+  return renderNode(node, context)
+}
+
+function renderNode(node: VNodeType, context: RenderContext): string {
+  switch (node.type) {
+    case 'col':
+      return renderCol(node, context)
+    case 'row':
+      return renderRow(node, context)
+    case 'box':
+      return renderBox(node, context)
+    case 'spacer':
+      return renderSpacer(node)
+    case 'slot':
+      return renderSlot(node, context)
+    case 'text':
+      return renderText(node)
+    case 'icon':
+      return renderIcon(node)
+    case 'image':
+      return renderImage(node)
+    case 'component':
+      return renderComponent(node, context)
+    default:
+      return `<!-- unknown type: ${node.type} -->`
+  }
+}
+
+function renderChildren(children: VNodeType[] | undefined, context: RenderContext): string {
+  if (!children || children.length === 0) return ''
+  return children.map(child => renderNode(child, context)).join('\n')
+}
+
+// ============================================================
+// Primitive renderers
+// ============================================================
+
+function renderCol(node: VNodeType, context: RenderContext): string {
+  const classes: string[] = ['flex', 'flex-col']
+  const { gap, align, padding } = node.props as { gap?: SpacingToken; align?: AlignToken; padding?: SpacingToken }
+
+  if (gap) {
+    validateSpacing(gap)
+    classes.push(SPACING_GAP[gap])
+  }
+  if (align) classes.push(ALIGN_ITEMS[align])
+  if (padding) {
+    validateSpacing(padding)
+    classes.push(SPACING_PADDING[padding])
+  }
+
+  const childrenHtml = renderChildren(node.children, context)
+  return `<div data-primitive="col" data-node-id="${node.id}" class="${classes.join(' ')}">${childrenHtml}</div>`
+}
+
+function renderRow(node: VNodeType, context: RenderContext): string {
+  const classes: string[] = ['flex', 'flex-row']
+  const { gap, align, padding } = node.props as { gap?: SpacingToken; align?: AlignToken; padding?: SpacingToken }
+
+  if (gap) {
+    validateSpacing(gap)
+    classes.push(SPACING_GAP[gap])
+  }
+  // Row defaults to items-center
+  classes.push(align ? ALIGN_ITEMS[align] : 'items-center')
+  if (padding) {
+    validateSpacing(padding)
+    classes.push(SPACING_PADDING[padding])
+  }
+
+  const childrenHtml = renderChildren(node.children, context)
+  return `<div data-primitive="row" data-node-id="${node.id}" class="${classes.join(' ')}">${childrenHtml}</div>`
+}
+
+function renderBox(node: VNodeType, context: RenderContext): string {
+  const classes: string[] = []
+  const { padding, bg, radius } = node.props as { padding?: SpacingToken; bg?: BackgroundToken; radius?: RadiusToken }
+
+  if (padding) {
+    validateSpacing(padding)
+    classes.push(SPACING_PADDING[padding])
+  }
+  if (bg) {
+    validateBackground(bg)
+    classes.push(BG_CLASS[bg])
+  }
+  if (radius) {
+    validateRadius(radius)
+    classes.push(RADIUS_CLASS[radius])
+  }
+
+  const childrenHtml = renderChildren(node.children, context)
+  return `<div data-primitive="box" data-node-id="${node.id}" class="${classes.join(' ')}">${childrenHtml}</div>`
+}
+
+function renderSpacer(node: VNodeType): string {
+  const { size } = node.props as { size?: SpacingToken }
+
+  if (size) {
+    validateSpacing(size)
+    return `<div data-primitive="spacer" data-node-id="${node.id}" class="${SPACING_SIZE[size]} shrink-0"></div>`
+  }
+  return `<div data-primitive="spacer" data-node-id="${node.id}" class="flex-1"></div>`
+}
+
+function renderSlot(node: VNodeType, context: RenderContext): string {
+  const { name } = node.props as { name: string }
+  const state = context.state || 'default'
+
+  if (context.slots && context.slots[name]) {
+    const stateMapping = context.slots[name]
+    const content = stateMapping[state] || stateMapping.default
+
+    if (content) {
+      return renderNode(content, context)
+    }
+  }
+
+  return `<div data-primitive="slot" data-slot-name="${name}" data-node-id="${node.id}"><!-- slot: ${name} --></div>`
+}
+
+function renderText(node: VNodeType): string {
+  const classes: string[] = []
+  const { content, size, weight, color } = node.props as {
+    content?: string
+    size?: SizeToken
+    weight?: WeightToken
+    color?: ColorToken
+  }
+
+  if (size) {
+    validateTypographySize(size)
+    classes.push(SIZE_CLASS[size])
+  }
+  if (weight) {
+    validateTypographyWeight(weight)
+    classes.push(WEIGHT_CLASS[weight])
+  }
+  if (color) {
+    validateColor(color)
+    classes.push(COLOR_CLASS[color])
+  }
+
+  return `<span data-primitive="text" data-node-id="${node.id}" class="${classes.join(' ')}">${escapeHtml(content || '')}</span>`
+}
+
+function renderIcon(node: VNodeType): string {
+  const classes: string[] = ['inline-flex', 'items-center', 'justify-center']
+  const { name, size, color } = node.props as { name: string; size?: SizeToken; color?: ColorToken }
+
+  if (size) {
+    validateTypographySize(size)
+    classes.push(ICON_SIZE_CLASS[size])
+  }
+  if (color) {
+    validateColor(color)
+    classes.push(COLOR_CLASS[color])
+  }
+
+  return `<span data-primitive="icon" data-icon="${escapeHtml(name)}" data-node-id="${node.id}" class="${classes.join(' ')}"><!-- icon: ${escapeHtml(name)} --></span>`
+}
+
+function renderImage(node: VNodeType): string {
+  const classes: string[] = ['max-w-full']
+  const { src, alt, fit } = node.props as { src: string; alt?: string; fit?: FitToken }
+
+  if (fit) classes.push(FIT_CLASS[fit])
+
+  return `<img data-primitive="image" data-node-id="${node.id}" src="${escapeHtml(src)}" alt="${escapeHtml(alt || '')}" class="${classes.join(' ')}" />`
+}
+
+function renderComponent(node: VNodeType, context: RenderContext): string {
+  const componentName = node.componentName || 'Unknown'
+
+  if (context.renderComponent) {
+    return context.renderComponent(componentName, node.props, node.children)
+  }
+
+  // Default: render children wrapped in component marker
+  const childrenHtml = renderChildren(node.children, context)
+  return `<div data-component="${componentName}" data-node-id="${node.id}">${childrenHtml}</div>`
+}
+
+// ============================================================
+// Utilities
+// ============================================================
+
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;')
+}