🌊 Ripple

A powerful, lightweight React form library that generates dynamic forms from JSON Schema with Material-UI components.

✨ Features

• 🚀 Dynamic Form Generation - Create complex forms from JSON Schema
• 🎨 Material-UI Integration - Beautiful, accessible components out of the box
• 🔧 25+ Form Controls - Rich set of input types and controls
• ✅ Built-in Validation - Client-side validation with react-hook-form
• 🎯 Conditional Logic - Show/hide fields based on other field values
• 🔄 Real-time Updates - Live form state management and updates
• 📝 Code Editor Support - Built-in CodeMirror integration
• 🎭 Customizable Theming - Full control over styling and appearance
• 📱 Responsive Design - Mobile-friendly form layouts
• 🔗 Peer Dependencies - Optimized for mono-repository setups

🚀 Quick Start

Installation

npm install @boltic/ripple

Peer Dependencies

Ripple requires the following peer dependencies to be installed in your project:

npm install @emotion/react @emotion/styled @mui/material react react-dom

Basic Usage

import React from 'react';
import FormBuilder from '@boltic/ripple';

const schema = [
  {
    name: 'firstName',
    label: 'First Name',
    type: 'text',
    meta: {
      displayName: 'First Name'
    }
  },
  {
    name: 'email',
    label: 'Email Address',
    type: 'email',
    meta: {
      displayName: 'Email'
    }
  },
  {
    name: 'age',
    label: 'Age',
    type: 'number',
    meta: {
      displayName: 'Your Age'
    }
  }
];

const MyForm = () => {
  const handleSubmit = (formData) => {
    console.log('Form submitted:', formData);
  };

  const handleChange = (changedField, formState) => {
    console.log('Field changed:', changedField.field, changedField.value);
  };

  return (
    <FormBuilder
      schema={schema}
      onSubmit={handleSubmit}
      onChange={handleChange}
    />
  );
};

export default MyForm;

📋 Available Form Controls

Ripple supports a comprehensive set of form controls:

| Control Type | Description | Schema Type | |--------------|-------------|-------------| | Text Input | Single-line text input | text | | Email | Email validation input | email | | Password | Password input with masking | password | | Number | Numeric input with validation | number | | Textarea | Multi-line text input | textarea | | Select | Dropdown selection | select | | Multi-Select | Multiple option selection | multiselect | | Radio | Radio button group | radio | | Radio Button | Individual radio buttons | radiobutton | | Checkbox | Checkbox input | checkbox | | Switch/Toggle | Toggle switch | toggle | | Autocomplete | Searchable dropdown | autocomplete | | Date Picker | Date selection | date | | File Upload | File upload with preview | file | | Phone | Phone number input | phone | | Slider | Range slider | slider | | Code Editor | CodeMirror-based editor | code | | Array | Dynamic array of fields | array | | Object | Nested object fields | object | | Key-Value | Key-value pair input | keyvalue | | Multiple Field | Multiple related fields | multiplefield | | Suggestion Input | Input with suggestions | suggestion | | Section | Form section grouping | section | | Accordion | Collapsible section | accordion | | Divider | Visual separator | divider | | Button | Action buttons | button | | Hidden | Hidden form fields | hidden |

🎯 Advanced Features

Conditional Logic

Show or hide fields based on other field values:

const schema = [
  {
    name: 'hasAccount',
    label: 'Do you have an account?',
    type: 'checkbox'
  },
  {
    name: 'loginEmail',
    label: 'Email',
    type: 'email',
    meta: {
      dependencies: {
        logic: 'AND',
        conditions: [
          {
            field: 'hasAccount',
            operator: 'equals',
            value: true
          }
        ]
      }
    }
  }
];

Array Fields

Create dynamic arrays of form fields:

const schema = [
  {
    name: 'contacts',
    label: 'Contacts',
    type: 'array',
    meta: {
      children: [
        {
          name: 'name',
          label: 'Contact Name',
          type: 'text'
        },
        {
          name: 'email',
          label: 'Contact Email',
          type: 'email'
        }
      ]
    }
  }
];

Code Editor

Integrate CodeMirror for code editing:

const schema = [
  {
    name: 'jsonConfig',
    label: 'JSON Configuration',
    type: 'code',
    meta: {
      language: 'json',
      theme: 'dark'
    }
  }
];

Custom Validation

Add custom validation rules:

const schema = [
  {
    name: 'username',
    label: 'Username',
    type: 'text',
    meta: {
      validation: {
        required: 'Username is required',
        minLength: {
          value: 3,
          message: 'Username must be at least 3 characters'
        }
      }
    }
  }
];

🔧 API Reference

FormBuilder Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | schema | Field[] | [] | Form schema definition | | form | object | {} | Initial form values | | name | string | - | Form identifier | | onChange | function | - | Field change callback | | onSubmit | function | - | Form submit callback | | onFocus | function | - | Field focus callback | | onCustom | function | - | Custom event callback | | buttonSchema | object | - | Custom button configuration | | loading | boolean | false | Show loading state | | isLoading | boolean | false | Disable form during loading | | useDefaultButtons | boolean | true | Show default submit/cancel buttons | | viewOnly | boolean | false | Render form in read-only mode | | sx | object | - | Material-UI sx prop for styling |

Field Schema

interface Field {
  name: string;           // Field identifier
  label?: string;         // Display label
  type?: string;          // Control type
  meta?: {
    displayName?: string;
    displayType?: string;
    options?: Array<{     // For select/radio controls
      value: any;
      label: string;
    }>;
    dependencies?: {      // Conditional logic
      logic?: 'AND' | 'OR';
      conditions?: Array<{
        field: string;
        operator: string;
        value: any;
      }>;
    };
    children?: Field[];   // For array/object controls
    validation?: object;  // Validation rules
    [key: string]: any;   // Additional properties
  };
}

🎨 Theming & Customization

Ripple integrates seamlessly with Material-UI's theming system:

import { ThemeProvider, createTheme } from '@mui/material/styles';
import FormBuilder from '@boltic/ripple';

const theme = createTheme({
  palette: {
    primary: {
      main: '#1976d2',
    },
  },
  components: {
    MuiTextField: {
      styleOverrides: {
        root: {
          marginBottom: '16px',
        },
      },
    },
  },
});

const App = () => (
  <ThemeProvider theme={theme}>
    <FormBuilder schema={schema} />
  </ThemeProvider>
);

🏗️ Architecture

Ripple is built with modern React patterns and best practices:

• React Hook Form - Performant form state management
• Material-UI - Consistent, accessible UI components
• TypeScript - Full type safety and IntelliSense
• CodeMirror - Advanced code editing capabilities
• Modular Design - Tree-shakable, component-based architecture

Development Setup

# Clone the repository
git clone <repo-link>
cd ripple

# Install dependencies
npm install

# Start development server
npm start

# Build the library
npm run build

# Run tests
npm test

📦 Publishing to npm

The package is configured for npm publish. Only dist and README.md are included in the tarball.

1. Log in (one-time): npm login
2. Bump version: npm version patch|minor|major
3. Publish: npm publish

prepublishOnly runs npm run build before publish, so a fresh build is always included. To publish this scoped package as public, use: npm publish --access public.

🙋‍♂️ Support

• Email: [email protected], [email protected]

🚀 Roadmap

• [ ] Add more form controls (URL, Color Picker, etc.)
• [ ] Enhanced validation system
• [ ] Form builder UI/visual editor
• [ ] Improved accessibility features
• [ ] Performance optimizations
• [ ] Comprehensive test suite

Made with ❤️ by the Boltic Team