Ahamatic - Modern Material-UI Wrapper Component

A comprehensive, enterprise-ready Material-UI wrapper component for React applications, providing authentication, navigation, and layout management with modern best practices.

🚀 Features

• Modern React Patterns: Built with React 18+ using hooks, context, and functional components
• Material-UI v6: Latest Material-UI components with optimized performance
• Authentication Integration: Built-in support for Volenday SDK and OpenIAM
• Responsive Design: Mobile-first approach with responsive sidebar and navigation
• Accessibility: WCAG compliant with proper ARIA attributes and keyboard navigation
• Performance Optimized: Lazy loading, memoization, and optimized re-renders
• TypeScript Ready: Comprehensive PropTypes and JSDoc documentation
• Customizable: Extensive styling and configuration options

📦 Installation

npm install @volenday/ahamatic

Peer Dependencies

Make sure you have the following peer dependencies installed:

npm install @mui/material@^6.1.1 @mui/icons-material@^6.1.1 @emotion/react@^11.13.3 @emotion/styled@^11.13.0 react@^18.3.1 react-dom@^18.3.1

🏗️ Basic Usage

import React from 'react';
import { MUIWrapper } from '@volenday/ahamatic';
import { Dashboard, People, Settings } from '@mui/icons-material';

const App = () => {
	const menuItems = [
		{
			name: 'Dashboard',
			route: '/dashboard',
			icon: <Dashboard />
		},
		{
			name: 'Users',
			route: '/users',
			icon: <People />
		},
		{
			name: 'Settings',
			route: '/settings',
			icon: <Settings />,
			children: [
				{
					name: 'General',
					route: '/settings/general'
				},
				{
					name: 'Security',
					route: '/settings/security'
				}
			]
		}
	];

	const userAccount = {
		FirstName: 'John',
		LastName: 'Doe',
		EmailAddress: '[email protected]',
		Photo: {
			url: 'https://example.com/avatar.jpg'
		}
	};

	return (
		<MUIWrapper
			title="My Application"
			menus={menuItems}
			account={userAccount}
			selectedMenu="/dashboard"
			onLogout={() => console.log('Logout clicked')}
			onProfile={() => console.log('Profile clicked')}
			router={{
				push: path => console.log('Navigate to:', path)
			}}>
			<div>
				<h1>Welcome to your dashboard!</h1>
				<p>Your main content goes here.</p>
			</div>
		</MUIWrapper>
	);
};

export default App;

🎨 Advanced Configuration

Custom Styling

const customStyles = {
	headerStyles: {
		root: {
			background: 'linear-gradient(45deg, #FE6B8B 30%, #FF8E53 90%)',
			color: '#fff',
			height: '70px'
		},
		userHeader: {
			avatar: { width: 40, height: 40 }
		}
	},
	sidebarStyles: {
		root: {
			backgroundColor: '#1a1a1a',
			color: '#fff'
		},
		listItemText: {
			color: '#fff'
		}
	},
	mainContentStyles: {
		root: {
			backgroundColor: '#f5f5f5',
			minHeight: '100vh'
		}
	}
};

<MUIWrapper
	title="Custom Styled App"
	headerStyles={customStyles.headerStyles}
	sidebarStyles={customStyles.sidebarStyles}
	mainContentStyles={customStyles.mainContentStyles}
	// ... other props
>
	{/* Your content */}
</MUIWrapper>;

Authentication Configuration

<MUIWrapper
	authenticate={true}
	authenticateRequired={true}
	authenticateOpenIAm={true}
	apiKey="your-api-key"
	environment="production"
	eu={false}
	onVerify={data => {
		console.log('Authentication verified:', data);
		// Handle authentication success
	}}
	// ... other props
>
	{/* Your authenticated content */}
</MUIWrapper>

Internationalization

const languageConfig = {
	languages: ['en', 'es', 'fr', 'de'],
	selectedLanguage: 'en',
	showLanguageSelector: true,
	onLanguageChange: event => {
		const newLanguage = event.target.value;
		console.log('Language changed to:', newLanguage);
		// Handle language change
	}
};

<MUIWrapper
	{...languageConfig}
	// ... other props
>
	{/* Your internationalized content */}
</MUIWrapper>;

📋 API Reference

Core Props

| Prop | Type | Default | Description | | ---------- | ----------------- | ------------ | -------------------------- | | children | ReactNode | Required | Main content to be wrapped | | title | string | '' | Application or page title | | menus | Array<MenuItem> | [] | Navigation menu items | | account | UserAccount | null | User account information |

Authentication Props

| Prop | Type | Default | Description | | ---------------------- | --------- | ------- | -------------------------------- | | authenticate | boolean | false | Enable authentication | | authenticateRequired | boolean | true | Require authentication | | apiKey | string | '' | API key for authentication | | environment | string | '' | Environment (dev, staging, prod) |

Layout Props

| Prop | Type | Default | Description | | -------------------- | --------- | ------- | -------------------------- | | sidebar | boolean | true | Show sidebar navigation | | sidebarCollapsible | boolean | true | Allow sidebar collapse | | embed | boolean | false | Embedded mode (no sidebar) | | hasFooter | boolean | true | Show footer |

Styling Props

| Prop | Type | Default | Description | | ------------------- | --------------- | ------- | ----------------------------- | | headerStyles | HeaderStyles | {} | Header styling configuration | | sidebarStyles | SidebarStyles | {} | Sidebar styling configuration | | mainContentStyles | ContentStyles | {} | Main content styling |

🎯 Type Definitions

/**
 * @typedef {Object} MenuItem
 * @property {string} name - Display name
 * @property {string} [route] - Navigation route
 * @property {ReactNode} [icon] - Menu icon
 * @property {Array<MenuItem>} [children] - Submenu items
 */

/**
 * @typedef {Object} UserAccount
 * @property {string} FirstName - User's first name
 * @property {string} LastName - User's last name
 * @property {string} EmailAddress - User's email
 * @property {Object} [Photo] - User's photo
 * @property {string} Photo.url - Photo URL
 */

/**
 * @typedef {Object} Router
 * @property {Function} push - Navigation function
 */

🔧 Development

Prerequisites

• Node.js 18+
• React 18+
• Material-UI v6+

Setup

# Clone the repository
git clone https://github.com/Volenday/ahamatic.git

# Install dependencies
cd ahamatic
npm install

# Start Storybook for development
npm run storybook

Building

# Build for production
npm run compile

# Clean build artifacts
npm run clean

📖 Storybook Examples

Run Storybook to see interactive examples:

npm run storybook

Navigate to http://localhost:6006 to view the component library.

🌟 Best Practices

Performance Optimization

1. Lazy Loading: The wrapper uses React.lazy() for optimal code splitting
2. Memoization: Components are wrapped with React.memo() to prevent unnecessary re-renders
3. Callback Optimization: Event handlers are memoized with useCallback()

Accessibility

1. ARIA Labels: All interactive elements have proper ARIA labels
2. Keyboard Navigation: Full keyboard accessibility support
3. Screen Reader Support: Semantic HTML and proper headings

Customization

1. Theme Integration: Seamlessly integrates with Material-UI themes
2. CSS-in-JS: Uses emotion for dynamic styling
3. Responsive Design: Mobile-first approach with breakpoint-based layouts

🐛 Troubleshooting

Common Issues

Sidebar not responding on mobile

• Ensure you have the latest version of Material-UI
• Check that useMediaQuery is working properly

Authentication not working

• Verify your API key and environment settings
• Check network connectivity and CORS settings

Styling conflicts

• Make sure you're not overriding Material-UI's base styles
• Use the provided styling props instead of external CSS

📄 License

UNLICENSED - Copyright © 2020-2025 Volenday. All rights reserved.

🤝 Contributing

This is a private repository. For internal contributions, please follow the established development workflow and submit pull requests for review.

📞 Support

For support, please contact the development team or create an issue in the internal project management system.