@delightui/components 0.1.105 → 0.1.107

package/docs/components/molecules/ModalProvider.md

@@ -0,0 +1,205 @@
+# ModalProvider
+
+## Description
+
+Context provider component that manages modal state across your application. The ModalProvider enables programmatic modal management by maintaining a centralized registry of active modals and providing functions to open and close them from anywhere in your component tree.
+
+## Aliases
+
+- ModalProvider
+- ModalContext
+
+## Props Breakdown
+
+**Extends:** Standalone interface (no HTML element inheritance)
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `children` | `ReactNode` | - | Yes | Child components that will have access to modal context |
+
+## Examples
+
+### Basic Setup
+
+```tsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { ModalProvider } from '@delightui/components';
+import App from './App';
+
+ReactDOM.createRoot(document.getElementById('root')).render(
+  <ModalProvider>
+    <App />
+  </ModalProvider>
+);
+```
+
+### With Theme Provider
+
+```tsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { ModalProvider, ThemeProvider } from '@delightui/components';
+import App from './App';
+
+ReactDOM.createRoot(document.getElementById('root')).render(
+  <ThemeProvider theme="dark">
+    <ModalProvider>
+      <App />
+    </ModalProvider>
+  </ThemeProvider>
+);
+```
+
+### Multiple Provider Setup
+
+```tsx
+import React from 'react';
+import { 
+  ModalProvider, 
+  ThemeProvider, 
+  NotificationProvider 
+} from '@delightui/components';
+
+function Providers({ children }) {
+  return (
+    <ThemeProvider theme="light">
+      <NotificationProvider>
+        <ModalProvider>
+          {children}
+        </ModalProvider>
+      </NotificationProvider>
+    </ThemeProvider>
+  );
+}
+
+export default function App() {
+  return (
+    <Providers>
+      <YourAppContent />
+    </Providers>
+  );
+}
+```
+
+## Usage Notes
+
+### Provider Placement
+
+- **Place at application root**: The ModalProvider should be placed as high as possible in your component tree
+- **Above modal consumers**: All components that use `useModal` must be children of ModalProvider
+- **Order matters**: If using multiple providers, ModalProvider should typically be inner to theme providers
+
+### State Management
+
+- **Centralized**: All modal state is managed centrally by the provider
+- **Automatic cleanup**: Modals are automatically cleaned up when closed
+- **Multiple modals**: Supports multiple simultaneous modals with unique IDs
+- **Render order**: Modals render in the order they were opened
+
+### Performance
+
+- **Memoized rendering**: Modal components are memoized to prevent unnecessary re-renders
+- **Efficient updates**: Only affected modals re-render when state changes
+- **Memory management**: Closed modals are immediately removed from memory
+
+## Best Practices
+
+1. **Single provider instance**: Use only one ModalProvider per application
+2. **Root level placement**: Place the provider at or near your application root
+3. **Consistent placement**: Keep provider placement consistent across your app
+4. **Error boundaries**: Consider wrapping with error boundaries for robust error handling
+
+## Integration Examples
+
+### With React Router
+
+```tsx
+import { BrowserRouter } from 'react-router-dom';
+import { ModalProvider } from '@delightui/components';
+
+function App() {
+  return (
+    <BrowserRouter>
+      <ModalProvider>
+        <Routes>
+          <Route path="/" element={<HomePage />} />
+          <Route path="/dashboard" element={<Dashboard />} />
+        </Routes>
+      </ModalProvider>
+    </BrowserRouter>
+  );
+}
+```
+
+### With Redux
+
+```tsx
+import { Provider as ReduxProvider } from 'react-redux';
+import { ModalProvider } from '@delightui/components';
+import { store } from './store';
+
+function App() {
+  return (
+    <ReduxProvider store={store}>
+      <ModalProvider>
+        <AppContent />
+      </ModalProvider>
+    </ReduxProvider>
+  );
+}
+```
+
+### Error Boundary Integration
+
+```tsx
+import { ErrorBoundary } from 'react-error-boundary';
+import { ModalProvider } from '@delightui/components';
+
+function ErrorFallback({ error }) {
+  return (
+    <div>
+      <h2>Something went wrong:</h2>
+      <pre>{error.message}</pre>
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <ErrorBoundary FallbackComponent={ErrorFallback}>
+      <ModalProvider>
+        <AppContent />
+      </ModalProvider>
+    </ErrorBoundary>
+  );
+}
+```
+
+## TypeScript Support
+
+The ModalProvider is fully typed and will provide proper TypeScript intellisense:
+
+```tsx
+import { ReactNode } from 'react';
+import { ModalProvider } from '@delightui/components';
+
+interface AppProvidersProps {
+  children: ReactNode;
+}
+
+function AppProviders({ children }: AppProvidersProps) {
+  return (
+    <ModalProvider>
+      {children}
+    </ModalProvider>
+  );
+}
+```
+
+## Related Components
+
+- **[useModal Hook](./useModal.md)** - Hook for programmatic modal management
+- **[Modal](./Modal.md)** - Base modal component
+- **[ModalHeader](./ModalHeader.md)** - Modal header component
+- **[ModalFooter](./ModalFooter.md)** - Modal footer component