Ripple React Wrapper

A lightweight wrapper component that enables seamless integration of React components within the Ripple framework.

Overview

The Ripple React Wrapper allows you to embed existing React components into Ripple applications, providing a bridge between the two frameworks. This is particularly useful when migrating from React to Ripple or when you want to reuse existing React components in a Ripple project.

Features

• 🔄 Seamless Integration: Embed React components directly in Ripple
• 🎯 Type Safety: Full TypeScript support with proper type definitions
• 🚀 Performance: Efficient mounting and unmounting of React components
• 📦 Lightweight: Minimal overhead with clean API
• 🔧 Flexible: Pass props and HTML attributes easily

Installation

npm install ripple-react-wrapper
# or
pnpm add ripple-react-wrapper
# or
yarn add ripple-react-wrapper

Requirements

• Node.js >= 20.0.0
• React >= 18.2.0
• Ripple >= 0.2.35

Usage

Basic Example

import { ReactWrapper } from 'ripple-react-wrapper';
import MyReactComponent from './MyReactComponent';

export component MyRippleComponent() {
  <ReactWrapper 
    component={MyReactComponent} 
    $props={{ title: "Hello from Ripple!" }}
    class="my-wrapper"
  />
}

React Component Setup

Important: React components used with this wrapper must include the following import at the top:

import * as React from 'react';

Example React component:

import * as React from 'react'; // Required!
import { useState } from 'react';

interface MyComponentProps {
  title?: string;
  initialCount?: number;
}

export default function MyComponent({ title = "Counter", initialCount = 0 }: MyComponentProps) {
  const [count, setCount] = useState(initialCount);

  return (
    <div>
      <h2>{title}</h2>
      <p>Count: {count}</p>
      <button onClick={() => setCount(count + 1)}>
        Increment
      </button>
    </div>
  );
}

Advanced Usage

import { ReactWrapper } from 'ripple-react-wrapper';
import ComplexComponent from './ComplexComponent';

export component AdvancedExample() {
  let componentProps = {
    data: [1, 2, 3, 4, 5],
    onItemClick: (item) => console.log('Clicked:', item),
    theme: 'dark'
  };

  <ReactWrapper 
    component={ComplexComponent}
    $props={componentProps}
    style="border: 1px solid #ccc; padding: 16px;"
    data-testid="react-wrapper"
  />
}

API Reference

ReactWrapper Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | component | ComponentType<any> | ✅ | The React component to render | | $props | Record<string, any> | ❌ | Props to pass to the React component | | ...otherProps | any | ❌ | Additional HTML attributes for the wrapper div |

Types

interface ReactWrapperProps {
  component: ComponentType<any>;
  $props?: Record<string, any>;
  [key: string]: any;
}

type WrappableReactComponent<P = {}> = ComponentType<P>;
type ComponentProps<T> = T extends ComponentType<infer P> ? P : never;

How It Works

The wrapper creates a div element and uses React's createRoot API to mount your React component inside it. The component is properly unmounted when the Ripple component is destroyed, ensuring no memory leaks.

1. Mount: When the wrapper mounts, it creates a React root and renders your component
2. Props: Component props are passed through the $props attribute
3. Cleanup: When unmounting, the React root is properly cleaned up

Known Issues

• React components must include import * as React from 'react'; at the top
• TypeScript may show warnings for .ripple files (this is expected and being worked on)

Development

# Format code
npm run format

# Check formatting
npm run format:check

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.