@amritanshu3011/mdx-renderer 1.0.9 → 1.0.11

package/README.md

@@ -1,142 +1,236 @@
+
 ```markdown
 # MDX Renderer
 
-A robust, theme-able visualization and MDX rendering system for React applications. It supports both direct MDX file rendering and programmatic visualization injection (Intent-based UI).
+A flexible, extensible rendering engine for React. It transforms data (JSON) and MDX content into rich, interactive UI components.
+
+Designed for **Data-Driven UI**, it allows you to render specific components dynamically based on backend responses, while giving you the power to inject your own custom components or override built-in ones.
 
-## Installation
+## 📦 Installation
 
 ```bash
-npm install @amritanshu3011/mdx-renderer
+npm install @amritanshu3011/mdx-renderer echarts recharts lucide-react
+
+```
+
+### ⚠️ Import Styles
+
+You **must** import the base CSS in your application's entry point (e.g., `main.jsx` or `App.jsx`) for components to render correctly.
+
+```javascript
+import '@amritanshu3011/mdx-renderer/styles/base.css';
 
 ```
 
-## 1. Intent-Based Usage (Programmatic)
+---
 
-Use this pattern when you want to render specific components based on backend data (e.g., from an LLM or API). This effectively turns JSON responses into React UI.
+## 🚀 Quick Start (Data-Driven Mode)
 
-### Step 1: Wrap your App
+The core principle is simple: You provide an array of data objects, and the library renders the corresponding components.
 
 ```tsx
-import { VisualizationProvider } from '@amritanshu3011/mdx-renderer';
+import { IntentProvider, MDXRenderer } from '@amritanshu3011/mdx-renderer';
+import Content from './content.mdx'; // Optional MDX file
 
 function App() {
+  // Data from your API, Backend, or LLM
+  const dashboardData = [
+    {
+      type: 'line_chart',
+      data: {
+        title: 'Monthly Revenue',
+        xKey: 'month',
+        yKey: 'value',
+        points: [{ month: 'Jan', value: 4000 }, { month: 'Feb', value: 3000 }]
+      }
+    }
+  ];
+
   return (
-    <VisualizationProvider>
-      <YourAppContent />
-    </VisualizationProvider>
+    // IntentProvider handles Data, Theme, and Registry
+    <IntentProvider data={dashboardData}>
+      
+      {/* 1. Render content from MDX files */}
+      <MDXRenderer>
+        <Content />
+      </MDXRenderer>
+
+    </IntentProvider>
   );
 }
 
 ```
 
-### Step 2: Inject & Render
+In your `.mdx` file, simply use the dynamic tag:
 
-```tsx
-import { useVisualizations, visualizationRegistry } from '@amritanshu3011/mdx-renderer';
+```mdx
+# Dashboard
 
-function ResultsPage() {
-  const { visualizations, addVisualization } = useVisualizations();
+import { DynamicVisualizations } from '@amritanshu3011/mdx-renderer';
 
-  // Simulate receiving data from a backend
-  const handleLoadData = () => {
-    addVisualization({
-      type: 'pros_cons', // Key must match the registry (see table below)
-      data: {
-        title: 'React vs Angular',
-        pros: ['Virtual DOM', 'Huge Ecosystem'],
-        cons: ['Steep Learning Curve']
-      }
-    });
-  };
+Below is the dynamic analysis:
 
-  return (
-    <div>
-      <button onClick={handleLoadData}>Load Analysis</button>
-
-      {/* Render the Dynamic Components */}
-      <div className="results-container">
-        {visualizations.map((viz, index) => {
-          const Component = visualizationRegistry[viz.type];
-          
-          if (!Component) return null;
-          
-          return <Component key={index} {...viz.data} />;
-        })}
-      </div>
-    </div>
-  );
-}
+<DynamicVisualizations />
 
 ```
 
-## 2. Standard MDX Usage
+---
 
-Use this pattern if you are importing and rendering `.mdx` files directly.
+## 🧩 Reusability & Extension (The Registry Pattern)
 
-```tsx
-import { MDXRenderer, ThemeProvider } from '@amritanshu3011/mdx-renderer';
-import Content from './document.mdx';
+This library is designed to be **extended**. You are not limited to the built-in components. You can use the `registry` prop to:
+
+1. **Add** entirely new components (e.g., a Video Player, Map, or KPI Card).
+2. **Override** built-in components to match your design system.
+3. **Adapt** backend data structures to match component props.
+
+### Example: Adding a Custom Component
+
+**1. Create your component**
+
+```jsx
+// src/components/ImageViewer.jsx
+export const ImageViewer = ({ src, caption }) => (
+  <div className="card">
+    <img src={src} alt="Custom" />
+    <p>{caption}</p>
+  </div>
+);
+
+```
+
+**2. Register it in your App**
+
+```jsx
+import { ImageViewer } from './components/ImageViewer';
+
+const myRegistry = {
+  // Map the backend 'type' string to your React Component
+  'image_viewer': ImageViewer
+};
+
+function App() {
+  const data = [
+    { 
+      type: 'image_viewer', // Matches your registry key
+      data: { src: 'demo.jpg', caption: 'Injected Component' } 
+    }
+  ];
 
-function DocumentPage() {
   return (
-    <ThemeProvider>
-      <MDXRenderer>
-        <Content />
-      </MDXRenderer>
-    </ThemeProvider>
+    <IntentProvider data={data} registry={myRegistry}>
+      <MDXRenderer><Content /></MDXRenderer>
+    </IntentProvider>
   );
 }
 
 ```
 
-## Component Registry & Data Structures
+### Example: Adapting Data (Adapter Pattern)
 
-When using the intent-based approach, your backend must return the correct `type` string.
+If your backend API returns data that doesn't match the library's expected props, don't change the API. Just wrap the component!
 
-### Smart Analysis Blocks
+```jsx
+import { LineChart } from '@amritanshu3011/mdx-renderer';
 
-| Component | Type Key | Required Data Structure |
-| --- | --- | --- |
-| **Pros & Cons** | `pros_cons` | `{ title: string, pros: string[], cons: string[] }` |
-| **Comparison** | `comparison` | `{ title: string, items: [{ name, price, features[] }] }` |
-| **Flow Chart** | `flow` | `{ title: string, steps: [{ id, label, status }] }` |
-| **Concept Tree** | `concept_tree` | `{ title: string, data: { name, children: [] } }` |
-| **Sunburst** | `sunburst` | `{ title: string, data: { name, children: [{ name, value }] } }` |
-| **Composite** | `interactive_composite` | `{ title: string, selector: object, views: object }` |
+// Backend sends 'history', Library expects 'points'
+const CustomChartAdapter = (props) => {
+  const adaptedProps = {
+    ...props,
+    points: props.history // Remap the data
+  };
+  return <LineChart {...adaptedProps} />;
+};
 
-### Data Visualizations
+const myRegistry = {
+  'line_chart': CustomChartAdapter // Override the default handler
+};
+
+```
+
+---
 
-| Component | Type Key | Required Data Structure |
+## 📚 Built-in Component Reference
+
+The library comes with a suite of "Smart Components" ready to use.
+
+| Component Key | Description | Required Data Structure |
 | --- | --- | --- |
-| **Line Chart** | `line_chart` | `{ title: string, xAxisKey: string, data: object[], series: [{ key, color }] }` |
+| **`line_chart`** | Simple Line Chart | `{ title, xKey, yKey, points: [{x, y}] }` |
+| **`pros_cons`** | Two-column list | `{ title, pros: [], cons: [] }` |
+| **`comparison`** | Feature comparison table | `{ title, items: [{ name, price, features[] }] }` |
+| **`flow`** | Process flow diagram | `{ title, steps: [{ id, label, status }] }` |
+| **`concept_tree`** | Hierarchical tree view | `{ title, data: { name, children: [] } }` |
+| **`sunburst`** | Radial hierarchy chart | `{ title, data: { name, children: [{ name, value }] } }` |
+| **`interactive_composite`** | Tabbed view container | `{ title, selector: {}, views: {} }` |
+
+---
+## 🎨 Theming
+
+The `IntentProvider` accepts a theme object to customize your application's look. You can override colors, spacing, typography, and border radius.
 
-## Theme Customization
+### 1. Basic Customization (Safe Merging)
 
-You can inject a custom theme to match your brand colors.
+**Important:** To prevent errors, always merge your overrides with the `defaultTheme`. This ensures that required properties (like spacing or typography) are not missing.
 
 ```tsx
-import { ThemeProvider } from '@amritanshu3011/mdx-renderer';
+import { IntentProvider, defaultTheme } from '@amritanshu3011/mdx-renderer';
 
-const myTheme = {
+// Create your custom theme by overriding specific values
+const myBrandTheme = {
+  ...defaultTheme, // 1. Keep default structure
   colors: {
-    primary: '#007bff',
-    secondary: '#6c757d',
-    background: '#ffffff',
-    text: '#333333'
+    ...defaultTheme.colors, // 2. Keep default colors (like charts)
+    primary: '#ec4899',     // 3. Override Primary (Pink)
+    background: '#111827',  // Override Background
+    text: '#f9fafb'
   },
-  spacing: {
-    small: '8px',
-    medium: '16px',
-    large: '24px'
+  borderRadius: {
+    ...defaultTheme.borderRadius,
+    medium: '12px' // Rounder corners
   }
 };
 
-<ThemeProvider initialTheme={myTheme}>
-  <App />
-</ThemeProvider>
-
+function App() {
+  return (
+    <IntentProvider theme={myBrandTheme} data={...}>
+      <AppContent />
+    </IntentProvider>
+  );
+}
 ```
+**Important:** Here is the full type definition for reference:
 
-```
 
+```tsx
+type Theme = {
+  colors: {
+    primary: string;
+    secondary: string;
+    text: string;
+    textSecondary: string;
+    background: string;
+    cardBackground: string;
+    border: string;
+    chartLine: string;
+    chartBar: string;
+  };
+  spacing: {
+    small: string;   // e.g. '8px'
+    medium: string;  // e.g. '16px'
+    large: string;   // e.g. '32px'
+    xlarge: string;  // e.g. '48px'
+  };
+  typography: {
+    fontFamily: string;
+    h1Size: string;
+    h2Size: string;
+    bodySize: string;
+    smallSize: string;
+  };
+  borderRadius: {
+    small: string;
+    medium: string;
+  };
+};
 ```

package/dist/IntentProvider.d.ts

@@ -3,6 +3,7 @@ interface IntentProviderProps {
     children: React.ReactNode;
     data?: any[];
     theme?: any;
+    registry?: Record<string, React.ComponentType<any>>;
 }
 export declare const IntentProvider: React.FC<IntentProviderProps>;
 export {};

package/dist/IntentProvider.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { ThemeProvider } from './theme/ThemeContext';
 import { VisualizationProvider } from './context/VisualizationContext';
-export const IntentProvider = ({ children, data = [], theme }) => {
-    return (_jsx(ThemeProvider, { initialTheme: theme, children: _jsx(VisualizationProvider, { initialVisualizations: data, children: children }) }));
+export const IntentProvider = ({ children, data = [], theme, registry = {} // Default to empty
+ }) => {
+    return (_jsx(ThemeProvider, { initialTheme: theme, children: _jsx(VisualizationProvider, { initialVisualizations: data, customRegistry: registry, children: children }) }));
 };

package/dist/components/DynamicVisualizations.js

@@ -1,17 +1,19 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useVisualizations } from '../context/VisualizationContext';
-import { visualizationRegistry } from '../registry/visualizationRegistry';
 export const DynamicVisualizations = () => {
-    const { visualizations } = useVisualizations();
-    if (visualizations.length === 0)
+    // 1. Get the MERGED registry from Context (Defaults + User Custom)
+    const { visualizations, registry } = useVisualizations();
+    if (!visualizations || visualizations.length === 0)
         return null;
-    return (_jsx("div", { children: visualizations.map((viz, index) => {
-            const vizType = viz.type;
-            const Component = visualizationRegistry[vizType];
+    return (_jsx("div", { className: "w-full flex flex-col gap-8 my-8", children: visualizations.map((viz, index) => {
+            // 2. Look up component in the Context Registry
+            // We use string indexing because users can add ANY key
+            const Component = registry[viz.type];
             if (!Component) {
-                console.warn(`Unknown visualization type: ${viz.type}`);
-                return null;
+                console.warn(`MDX Renderer: Unknown visualization type "${viz.type}"`);
+                // Render a helpful error for the developer/user
+                return (_jsxs("div", { className: "p-4 border border-red-200 bg-red-50 text-red-600 rounded-lg text-sm font-mono", children: ["\u26A0\uFE0F Unknown component type: ", _jsx("strong", { children: viz.type })] }, index));
             }
-            return (_jsx("div", { children: _jsx(Component, { ...viz.data }) }, index));
+            return (_jsx("div", { className: "mdx-viz-block w-full", children: _jsx(Component, { ...viz.data }) }, index));
         }) }));
 };

package/dist/context/VisualizationContext.d.ts

@@ -1,13 +1,19 @@
-import React from 'react';
-import type { LLMResponse } from '../types/mockLLM';
+import { ReactNode, ComponentType } from 'react';
+export interface VisualizationItem {
+    type: string;
+    data: any;
+}
 interface VisualizationContextType {
-    visualizations: LLMResponse[];
-    addVisualization: (viz: LLMResponse) => void;
+    visualizations: VisualizationItem[];
+    addVisualization: (viz: VisualizationItem) => void;
     clearVisualizations: () => void;
+    registry: Record<string, ComponentType<any>>;
+}
+export interface VisualizationProviderProps {
+    children: ReactNode;
+    initialVisualizations?: VisualizationItem[];
+    customRegistry?: Record<string, ComponentType<any>>;
 }
-export declare const VisualizationProvider: ({ children, initialVisualizations }: {
-    children: React.ReactNode;
-    initialVisualizations?: any[];
-}) => import("react/jsx-runtime").JSX.Element;
+export declare const VisualizationProvider: ({ children, initialVisualizations, customRegistry }: VisualizationProviderProps) => import("react/jsx-runtime").JSX.Element;
 export declare const useVisualizations: () => VisualizationContextType;
 export {};

package/dist/context/VisualizationContext.js

@@ -1,21 +1,32 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import React, { createContext, useContext } from 'react';
+import React, { createContext, useContext, useState } from 'react';
+// Import your default registry to use as a base
+import { visualizationRegistry as defaultRegistry } from '../registry/visualizationRegistry';
 const VisualizationContext = createContext(undefined);
-export const VisualizationProvider = ({ children, initialVisualizations = [] }) => {
-    const [visualizations, setVisualizations] = React.useState(initialVisualizations);
+export const VisualizationProvider = ({ children, initialVisualizations = [], customRegistry = {} }) => {
+    const [visualizations, setVisualizations] = useState(initialVisualizations);
+    // 1. MERGE LOGIC: Combine defaults with user overrides
+    // Using useMemo is good practice here to prevent recreation on every render, 
+    // but for simplicity, direct object spread works too.
+    const mergedRegistry = { ...defaultRegistry, ...customRegistry };
+    // 2. Reactive State Update
     React.useEffect(() => {
         if (initialVisualizations.length > 0) {
             setVisualizations(initialVisualizations);
         }
     }, [initialVisualizations]);
     const addVisualization = (viz) => {
-        console.log('Storing visualization:', viz);
         setVisualizations(prev => [...prev, viz]);
     };
     const clearVisualizations = () => {
         setVisualizations([]);
     };
-    return (_jsx(VisualizationContext.Provider, { value: { visualizations, addVisualization, clearVisualizations }, children: children }));
+    return (_jsx(VisualizationContext.Provider, { value: {
+            visualizations,
+            addVisualization,
+            clearVisualizations,
+            registry: mergedRegistry // <--- Pass the merged registry to the app
+        }, children: children }));
 };
 export const useVisualizations = () => {
     const context = useContext(VisualizationContext);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritanshu3011/mdx-renderer",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "description": "Reusable MDX visualization library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",