@reallygoodwork/react-to-coral

Transform React components into Coral UI specifications.

Installation

npm install @reallygoodwork/react-to-coral
# or
pnpm add @reallygoodwork/react-to-coral
# or
yarn add @reallygoodwork/react-to-coral

Overview

This package parses React component source code and transforms it into a Coral UI specification. It extracts:

• Component structure and hierarchy
• Props and their TypeScript types
• State hooks (useState)
• Methods and event handlers
• Styles (inline styles and Tailwind classes)
• Imports

API Reference

Functions

transformReactComponentToSpec(component, options?)

Transforms a React component string into a Coral specification.

import { transformReactComponentToSpec } from '@reallygoodwork/react-to-coral'

const reactCode = `
import React, { useState } from 'react'

interface ButtonProps {
  label: string
  onClick?: () => void
  variant?: 'primary' | 'secondary'
}

export const Button: React.FC<ButtonProps> = ({ label, onClick, variant = 'primary' }) => {
  const [isHovered, setIsHovered] = useState(false)

  const handleClick = () => {
    if (onClick) onClick()
  }

  return (
    <button
      className="px-4 py-2 rounded-lg bg-blue-500 text-white hover:bg-blue-600"
      onClick={handleClick}
      onMouseEnter={() => setIsHovered(true)}
      onMouseLeave={() => setIsHovered(false)}
    >
      {label}
    </button>
  )
}
`

const spec = transformReactComponentToSpec(reactCode)

// Result:
// {
//   $schema: 'https://coral.design/schema.json',
//   name: 'Button',
//   componentName: 'Button',
//   elementType: 'button',
//   type: 'COMPONENT',
//   componentProperties: {
//     label: { type: 'string', value: 'label', optional: false },
//     onClick: { type: '() => void', value: 'onClick', optional: true },
//     variant: { type: "'primary' | 'secondary'", value: 'variant', optional: true }
//   },
//   stateHooks: [
//     { name: 'isHovered', setter: 'setIsHovered', initialValue: 'boolean' }
//   ],
//   methods: [
//     { name: 'handleClick', parameters: [] }
//   ],
//   styles: {
//     paddingInlineStart: '1rem',
//     paddingInlineEnd: '1rem',
//     paddingBlockStart: '0.5rem',
//     paddingBlockEnd: '0.5rem',
//     borderRadius: '0.5rem',
//     backgroundColor: '#3b82f6',
//     color: '#ffffff'
//   },
//   imports: [
//     { source: 'react', specifiers: [{ name: 'React', isDefault: true }, { name: 'useState' }] }
//   ],
//   children: []
// }

Parameters:

• component: string - React component source code
• options?: { skipValidation?: boolean } - Options
  • skipValidation - Skip input validation (default: false)

Returns:

• CoralRootNode - The Coral specification

Throws:

• Error if the component cannot be parsed or is invalid

Supported React Patterns

Function Components

// Arrow function
const MyComponent = () => { ... }

// Function declaration
function MyComponent() { ... }

// Export default
export default function MyComponent() { ... }

TypeScript Props

// Interface
interface Props {
  title: string
  count?: number
}

// Type alias
type Props = {
  title: string
  count?: number
}

// React.FC
const Component: React.FC<Props> = (props) => { ... }

// Inline destructuring
const Component = ({ title, count }: Props) => { ... }

State Hooks

const [count, setCount] = useState(0)
const [items, setItems] = useState<string[]>([])
const [user, setUser] = useState<User | null>(null)

Methods

const handleClick = () => { ... }
const handleSubmit = (e: FormEvent) => { ... }
const fetchData = async () => { ... }

Styles

// Tailwind classes
<div className="flex items-center p-4 bg-white">

// Inline styles
<div style={{ padding: '20px', backgroundColor: 'white' }}>

// Combined
<div className="flex" style={{ gap: '10px' }}>

Example: Complete Workflow

import { transformReactComponentToSpec } from '@reallygoodwork/react-to-coral'
import { coralToReact } from '@reallygoodwork/coral-to-react'

// 1. Parse React component
const originalCode = `
export const Card = ({ title, children }) => (
  <div className="bg-white rounded-lg shadow-md p-6">
    <h2 className="text-xl font-bold mb-4">{title}</h2>
    <div>{children}</div>
  </div>
)
`

const spec = transformReactComponentToSpec(originalCode)

// 2. Modify the specification
spec.styles.backgroundColor = '#f0f0f0'
spec.componentName = 'UpdatedCard'

// 3. Generate new React component
const { reactCode } = await coralToReact(spec)

Validation

The package validates input before processing:

• Checks for valid React component syntax
• Validates JSX structure
• Ensures proper component exports

import { transformReactComponentToSpec } from '@reallygoodwork/react-to-coral'

// Skip validation for trusted input
const spec = transformReactComponentToSpec(code, { skipValidation: true })

Limitations

• Only functional components are supported (no class components)
• Complex hooks beyond useState are not fully analyzed
• Dynamic style computations may not be captured
• Template literals in JSX are simplified

Related Packages

• @reallygoodwork/coral-core - Core Coral types
• @reallygoodwork/coral-to-react - Coral to React
• @reallygoodwork/coral-tw2css - Tailwind to CSS

License

MIT © Really Good Work