Skip to main content

@mapples/render

A powerful React rendering system that enables dynamic component rendering from JSON-like component definitions. This package provides a flexible way to build dynamic UIs by defining component trees as data structures and rendering them with registered React components.

Features​

  • 🎨 Dynamic Component Rendering: Render React components from JSON-like definitions
  • 📦 Component Registration: Register and manage reusable components
  • 🔗 Data Binding: Bind dynamic data to component properties
  • 🌳 Nested Components: Support for complex component hierarchies
  • ⚡ Performance Optimized: Memoized components for optimal rendering performance
  • 📘 TypeScript Support: Full TypeScript support with comprehensive type definitions

Installation​

npm install @mapples/render
# or
yarn add @mapples/render

Quick Start​

1. Register Components​

First, create a registry of components that can be rendered:

import { Button, Text, View } from 'react-native';

const registeredComponents = {
  Button: { Component: Button },
  Text: { Component: Text },
  View: { Component: View },
  // Add more components as needed
};

2. Wrap with RenderProvider​

Wrap your application with the RenderProvider to make components available:

import { RenderProvider } from '@mapples/render';

const App = () => (
  <RenderProvider components={registeredComponents}>
    <YourAppContent />
  </RenderProvider>
);

3. Define Component Structure​

Create a component definition object:

const rootComponent = {
  id: 'root',
  type: 'View',
  props: {
    style: { flex: 1, padding: 20 },
  },
  children: ['header', 'content'],
  childComponents: {
    header: {
      id: 'header',
      type: 'Text',
      props: {
        children: 'Welcome to Mapples Render!',
        style: { fontSize: 24, fontWeight: 'bold' },
      },
      children: [],
      childComponents: {},
    },
    content: {
      id: 'content',
      type: 'View',
      props: { style: { marginTop: 20 } },
      children: ['button'],
      childComponents: {
        button: {
          id: 'button',
          type: 'Button',
          props: {
            title: 'Click Me',
            onPress: () => console.log('Button pressed!'),
          },
          children: [],
          childComponents: {},
        },
      },
    },
  },
};

4. Render the Component​

Use the Render component to render your component tree:

import { Render } from '@mapples/render';

const YourAppContent = () => <Render root={rootComponent} />;

API Reference​

Components​

Render​

The main component for rendering component trees from definitions.

Props:

  • root: RenderComponentType - The root component definition to render
  • CustomRenderComponent?: FC<RenderComponentType> - Optional custom render component

Example:

<Render root={componentDefinition} />

RenderProvider​

Provider component that makes registered components available to the render system.

Props:

  • components: RegisteredComponents - Map of registered components
  • children: ReactNode - Child components

Example:

<RenderProvider components={registeredComponents}>
  <App />
</RenderProvider>

RenderComponent​

Default implementation for rendering individual components. This is used internally by the Render component.

Hooks​

useRender()​

Hook to access the render context and registered components.

Returns:

  • RenderContextType - The render context containing registered components

Example:

const { components } = useRender();
const ButtonComponent = components['Button']?.Component;

Types​

RenderComponentType​

Core interface representing a renderable component:

interface RenderComponentType {
  id: string; // Unique identifier
  type: string; // Component type name
  props: AnyObject & { zIndex?: number }; // Component props
  children: string[]; // Child component IDs
  childComponents: ChildComponents; // Child component definitions
  dataProps?: DataProps; // Data property bindings
  actionProps?: ActionPropsMap; // Action property configurations
}

DataProp​

Configuration for data properties:

interface DataProp {
  key: string; // Data key identifier
  active: boolean; // Whether the property is active
}

ActionProps​

Configuration for action properties:

interface ActionProps {
  type?: string; // Action type
  dataProp?: string; // Data property key
}

Advanced Usage​

Data Binding​

Bind dynamic data to component properties using dataProps:

const componentWithData = {
  id: 'dynamic-text',
  type: 'Text',
  props: { children: 'Default Text' },
  dataProps: {
    children: {
      key: 'userName',
      active: true,
    },
  },
  children: [],
  childComponents: {},
};

Custom Render Component​

Override the default rendering behavior with a custom component:

const CustomRenderer = ({ type, props, children }) => (
  <div className={`custom-${type}`} {...props}>
    {children}
  </div>
);

<Render root={componentDefinition} CustomRenderComponent={CustomRenderer} />;

Performance Considerations​

  • Components are automatically memoized to prevent unnecessary re-renders
  • Use stable component IDs to maintain proper memoization
  • Consider component tree depth for optimal performance
  • Register only the components you need to reduce bundle size

Error Handling​

The render system gracefully handles missing components by returning null instead of throwing errors. Always ensure your component types are properly registered in the RenderProvider.

Integration with Other Mapples Packages​

This package integrates seamlessly with other Mapples packages:

  • @mapples/state: For data binding and state management
  • @mapples/types: For shared type definitions
  • @mapples/ui: For pre-built UI components

Examples​

Simple Form​

const formComponent = {
  id: 'form',
  type: 'View',
  props: { style: { padding: 20 } },
  children: ['title', 'input', 'button'],
  childComponents: {
    title: {
      id: 'title',
      type: 'Text',
      props: { children: 'Contact Form', style: { fontSize: 20 } },
      children: [],
      childComponents: {},
    },
    input: {
      id: 'input',
      type: 'TextInput',
      props: {
        placeholder: 'Enter your name',
        style: { borderWidth: 1, padding: 10, marginVertical: 10 },
      },
      children: [],
      childComponents: {},
    },
    button: {
      id: 'button',
      type: 'Button',
      props: {
        title: 'Submit',
        onPress: () => console.log('Form submitted'),
      },
      children: [],
      childComponents: {},
    },
  },
};

Nested Layout​

const layoutComponent = {
  id: 'layout',
  type: 'View',
  props: { style: { flex: 1 } },
  children: ['header', 'content', 'footer'],
  childComponents: {
    header: {
      id: 'header',
      type: 'View',
      props: { style: { height: 60, backgroundColor: '#f0f0f0' } },
      children: ['header-text'],
      childComponents: {
        'header-text': {
          id: 'header-text',
          type: 'Text',
          props: {
            children: 'Header',
            style: { textAlign: 'center', marginTop: 20 },
          },
          children: [],
          childComponents: {},
        },
      },
    },
    content: {
      id: 'content',
      type: 'View',
      props: { style: { flex: 1, padding: 20 } },
      children: [],
      childComponents: {},
    },
    footer: {
      id: 'footer',
      type: 'View',
      props: { style: { height: 60, backgroundColor: '#f0f0f0' } },
      children: ['footer-text'],
      childComponents: {
        'footer-text': {
          id: 'footer-text',
          type: 'Text',
          props: {
            children: 'Footer',
            style: { textAlign: 'center', marginTop: 20 },
          },
          children: [],
          childComponents: {},
        },
      },
    },
  },
};

Contributing​

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

License​

MIT License - see the LICENSE file for details.

Support​

For support and questions, please visit our GitHub repository or contact us at mapples.org.

Interfaces​

Type Aliases​

Variables​

Functions​