@integrativedesigndevelopment/dashboard-core 0.0.2

package/README.md

@@ -0,0 +1,775 @@
+# @integrativedesigndevelopment/dashboard-core
+
+The foundational package for IDD Dashboard providing core components, plugin system, state management, and essential utilities.
+
+[![npm version](https://badge.fury.io/js/@integrativedesigndevelopment%2Fdashboard-core.svg)](https://www.npmjs.com/package/@integrativedesigndevelopment/dashboard-core)
+
+## 🚀 Quick Start
+
+```bash
+npm install @integrativedesigndevelopment/dashboard-core
+```
+
+```jsx
+import {
+  DashboardProvider,
+  SimpleButton,
+} from '@integrativedesigndevelopment/dashboard-core';
+
+function App() {
+  return (
+    <DashboardProvider>
+      <SimpleButton onClick={() => alert('Hello!')}>Click me</SimpleButton>
+    </DashboardProvider>
+  );
+}
+```
+
+## 📦 What's Included
+
+### Core Components
+
+- **SimpleButton** - Styled button component
+- **DashboardProvider** - Global state provider
+- **ErrorBoundary** - Error handling wrapper
+
+### Plugin System
+
+- **PluginManager** - Plugin lifecycle management
+- **get_all_plugins** - Plugin discovery utility
+- **useDashboard** - Dashboard context hook
+
+### State Management
+
+- **Actions** - Redux actions for plugins and notifications
+- **Hooks** - Custom React hooks for common operations
+
+### Utilities
+
+- **Array Safety** - Safe array operations
+- **Helpers** - Common utility functions
+- **Metrics** - Performance tracking utilities
+
+### Services
+
+- **Error Services** - Centralized error handling
+
+## 🔧 Installation
+
+```bash
+# npm
+npm install @integrativedesigndevelopment/dashboard-core
+
+# yarn
+yarn add @integrativedesigndevelopment/dashboard-core
+
+# pnpm
+pnpm add @integrativedesigndevelopment/dashboard-core
+```
+
+### Peer Dependencies
+
+```bash
+npm install react@^18.0.0 react-dom@^18.0.0
+```
+
+## 📖 API Reference
+
+### DashboardProvider
+
+The main provider component that wraps your entire dashboard application.
+
+```jsx
+import { DashboardProvider } from '@integrativedesigndevelopment/dashboard-core';
+
+function App() {
+  return (
+    <DashboardProvider
+      config={{
+        theme: 'light',
+        plugins: ['Dashboard', 'Content'],
+        apiEndpoint: '/api',
+      }}
+      initialState={{
+        user: null,
+        notifications: [],
+      }}>
+      <YourDashboard />
+    </DashboardProvider>
+  );
+}
+```
+
+**Props:**
+
+- `config?: DashboardConfig` - Dashboard configuration
+- `initialState?: Partial<DashboardState>` - Initial Redux state
+- `children: React.ReactNode` - Child components
+
+### useDashboard Hook
+
+Access dashboard state and utilities throughout your app.
+
+```jsx
+import { useDashboard } from '@integrativedesigndevelopment/dashboard-core';
+
+function MyComponent() {
+  const {
+    state, // Current dashboard state
+    dispatch, // Redux dispatch function
+    plugins, // Available plugins
+    config, // Dashboard configuration
+    notifications, // Current notifications
+  } = useDashboard();
+
+  return (
+    <div>
+      <h1>Active Plugins: {plugins.length}</h1>
+      <p>Notifications: {notifications.length}</p>
+    </div>
+  );
+}
+```
+
+### PluginManager
+
+Manages plugin lifecycle and registration.
+
+```jsx
+import { PluginManager } from '@integrativedesigndevelopment/dashboard-core';
+
+const pluginManager = new PluginManager({
+  plugins: [MyPlugin, AnotherPlugin],
+  config: {
+    autoLoad: true,
+    enableHotReload: true,
+  },
+});
+
+// Register a new plugin
+pluginManager.register(NewPlugin);
+
+// Get all active plugins
+const activePlugins = pluginManager.getActivePlugins();
+
+// Unregister a plugin
+pluginManager.unregister('plugin-id');
+```
+
+### SimpleButton
+
+A styled button component following IDD design system.
+
+```jsx
+import { SimpleButton } from '@integrativedesigndevelopment/dashboard-core';
+
+function MyComponent() {
+  return (
+    <SimpleButton
+      variant="primary"
+      size="medium"
+      disabled={false}
+      loading={false}
+      onClick={() => console.log('Clicked!')}
+      className="custom-class">
+      Click Me
+    </SimpleButton>
+  );
+}
+```
+
+**Props:**
+
+- `variant?: 'primary' | 'secondary' | 'danger' | 'ghost'` - Button style variant
+- `size?: 'small' | 'medium' | 'large'` - Button size
+- `disabled?: boolean` - Disabled state
+- `loading?: boolean` - Loading state with spinner
+- `onClick?: () => void` - Click handler
+- `className?: string` - Additional CSS classes
+- `children: React.ReactNode` - Button content
+
+## 🔌 Plugin System
+
+### Creating a Plugin
+
+```typescript
+import { IDDPlugin } from '@integrativedesigndevelopment/dashboard-core';
+
+const MyPlugin: IDDPlugin = {
+  id: 'my-plugin',
+  name: 'My Plugin',
+  version: '0.0.1',
+  order: 10,
+  tabs: [
+    {
+      id: 'main',
+      name: 'Main',
+      content: <MyPluginContent />,
+    },
+  ],
+  dashboardWidget: <MyWidget />,
+  settings: [
+    {
+      key: 'enabled',
+      label: 'Enable Plugin',
+      type: 'toggle',
+      defaultValue: true,
+    },
+  ],
+  onLoad: () => console.log('Plugin loaded'),
+  onUnload: () => console.log('Plugin unloaded'),
+};
+
+export default MyPlugin;
+```
+
+### Plugin Interface
+
+```typescript
+interface IDDPlugin {
+  id: string; // Unique plugin identifier
+  name: string; // Display name
+  version?: string; // Plugin version
+  order?: number; // Sidebar order (lower = higher)
+  icon?: React.ComponentType; // Custom icon component
+  tabs?: IDDPluginTab[]; // Plugin tabs
+  dashboardWidget?: React.ReactNode; // Dashboard widget
+  settings?: IDDPluginSetting[]; // Plugin settings
+  notifications?: IDDPluginNotification[]; // Plugin notifications
+  exports?: IDDPluginExport[]; // Exportable data
+  onLoad?: () => void; // Load callback
+  onUnload?: () => void; // Unload callback
+}
+```
+
+### Plugin Discovery
+
+```jsx
+import { get_all_plugins } from '@integrativedesigndevelopment/dashboard-core';
+
+// Get all available plugins
+const plugins = get_all_plugins();
+
+// Filter plugins by criteria
+const activePlugins = plugins.filter((plugin) => plugin.enabled);
+
+// Get plugin by ID
+const specificPlugin = plugins.find((plugin) => plugin.id === 'my-plugin');
+```
+
+## 🎯 State Management
+
+### Actions
+
+```jsx
+import { ActionTypes } from '@integrativedesigndevelopment/dashboard-core';
+
+// Plugin actions
+dispatch({
+  type: ActionTypes.LOAD_PLUGIN,
+  payload: { pluginId: 'my-plugin' },
+});
+
+dispatch({
+  type: ActionTypes.UNLOAD_PLUGIN,
+  payload: { pluginId: 'my-plugin' },
+});
+
+// Notification actions
+dispatch({
+  type: ActionTypes.ADD_NOTIFICATION,
+  payload: {
+    id: 'notif-1',
+    title: 'Success',
+    message: 'Operation completed',
+    type: 'success',
+  },
+});
+```
+
+### Custom Hooks
+
+```jsx
+import {
+  useAsyncOperation,
+  useDeleteUsers,
+  useGetUsers,
+  useUpdateUser,
+} from '@integrativedesigndevelopment/dashboard-core';
+
+function UserManagement() {
+  // Async operation with loading state
+  const { execute, loading, error } = useAsyncOperation(async (userId) => {
+    return await api.deleteUser(userId);
+  });
+
+  // User management hooks
+  const { users, loading: usersLoading } = useGetUsers();
+  const { updateUser } = useUpdateUser();
+  const { deleteUser } = useDeleteUsers();
+
+  return (
+    <div>
+      {usersLoading ? (
+        <div>Loading users...</div>
+      ) : (
+        users.map((user) => (
+          <div key={user.id}>
+            <span>{user.name}</span>
+            <button onClick={() => updateUser(user.id, { active: false })}>
+              Deactivate
+            </button>
+            <button onClick={() => deleteUser(user.id)}>Delete</button>
+          </div>
+        ))
+      )}
+    </div>
+  );
+}
+```
+
+## 📊 Metrics System
+
+### Performance Tracking
+
+```jsx
+import {
+  trackCLS,
+  trackFCP,
+  trackFID,
+  trackLCP,
+  trackTTFB,
+} from '@integrativedesigndevelopment/dashboard-core';
+
+// Track Core Web Vitals
+trackCLS((metric) => {
+  console.log('Cumulative Layout Shift:', metric);
+});
+
+trackFCP((metric) => {
+  console.log('First Contentful Paint:', metric);
+});
+
+trackFID((metric) => {
+  console.log('First Input Delay:', metric);
+});
+
+trackLCP((metric) => {
+  console.log('Largest Contentful Paint:', metric);
+});
+
+trackTTFB((metric) => {
+  console.log('Time to First Byte:', metric);
+});
+```
+
+### Custom Metrics
+
+```jsx
+import { trackCustomMetric } from '@integrativedesigndevelopment/dashboard-core';
+
+// Track custom events
+trackCustomMetric('plugin-load-time', {
+  pluginId: 'my-plugin',
+  loadTime: performance.now() - startTime,
+  timestamp: Date.now(),
+});
+```
+
+## 🛠 Utilities
+
+### Array Safety
+
+```jsx
+import {
+  safeArray,
+  safeMap,
+  safeFilter,
+} from '@integrativedesigndevelopment/dashboard-core';
+
+// Safe array operations that handle null/undefined
+const items = safeArray(possiblyNullArray);
+const mapped = safeMap(items, (item) => item.name);
+const filtered = safeFilter(items, (item) => item.active);
+```
+
+### Helpers
+
+```jsx
+import {
+  debounce,
+  throttle,
+  deepMerge,
+  formatDate,
+  generateId,
+} from '@integrativedesigndevelopment/dashboard-core';
+
+// Debounce function calls
+const debouncedSearch = debounce((query) => {
+  performSearch(query);
+}, 300);
+
+// Throttle function calls
+const throttledScroll = throttle(() => {
+  handleScroll();
+}, 100);
+
+// Deep merge objects
+const merged = deepMerge(defaultConfig, userConfig);
+
+// Format dates
+const formatted = formatDate(new Date(), 'YYYY-MM-DD');
+
+// Generate unique IDs
+const id = generateId();
+```
+
+## 🔧 Configuration
+
+### Dashboard Config
+
+```typescript
+interface DashboardConfig {
+  theme?: 'light' | 'dark' | 'auto';
+  plugins?: string[];
+  apiEndpoint?: string;
+  features?: {
+    notifications?: boolean;
+    metrics?: boolean;
+    errorBoundary?: boolean;
+  };
+  ui?: {
+    sidebar?: {
+      collapsible?: boolean;
+      defaultCollapsed?: boolean;
+    };
+    header?: {
+      showLogo?: boolean;
+      showUserMenu?: boolean;
+    };
+  };
+}
+```
+
+### Environment Configuration
+
+```jsx
+// Configure based on environment
+const config = {
+  apiEndpoint:
+    process.env.NODE_ENV === 'production'
+      ? 'https://api.example.com'
+      : 'http://localhost:3001',
+  features: {
+    metrics: process.env.NODE_ENV === 'production',
+    errorBoundary: true,
+  },
+};
+
+<DashboardProvider config={config}>
+  <App />
+</DashboardProvider>;
+```
+
+## 🧪 Testing
+
+### Component Testing
+
+```jsx
+import { render, screen } from '@testing-library/react';
+import {
+  DashboardProvider,
+  SimpleButton,
+} from '@integrativedesigndevelopment/dashboard-core';
+
+function renderWithProvider(component, config = {}) {
+  return render(
+    <DashboardProvider config={config}>{component}</DashboardProvider>
+  );
+}
+
+test('SimpleButton renders correctly', () => {
+  renderWithProvider(
+    <SimpleButton onClick={jest.fn()}>Test Button</SimpleButton>
+  );
+
+  expect(screen.getByRole('button')).toHaveTextContent('Test Button');
+});
+```
+
+### Plugin Testing
+
+```jsx
+import { PluginManager } from '@integrativedesigndevelopment/dashboard-core';
+
+test('plugin manager registers plugins correctly', () => {
+  const manager = new PluginManager();
+  const mockPlugin = {
+    id: 'test-plugin',
+    name: 'Test Plugin',
+    tabs: [],
+  };
+
+  manager.register(mockPlugin);
+
+  expect(manager.getPlugin('test-plugin')).toBe(mockPlugin);
+});
+```
+
+## 🎨 Styling
+
+### CSS Classes
+
+```css
+/* Core component styles */
+.idd-button {
+  @apply px-4 py-2 rounded-md font-medium transition-colors;
+}
+
+.idd-button-primary {
+  @apply bg-idd-primary text-white hover:bg-idd-primary-dark;
+}
+
+.idd-button-secondary {
+  @apply bg-gray-200 text-gray-900 hover:bg-gray-300;
+}
+
+.idd-dashboard-container {
+  @apply min-h-screen bg-gray-50;
+}
+
+.idd-sidebar {
+  @apply w-64 bg-white shadow-lg;
+}
+```
+
+### Theme Customization
+
+```jsx
+const customTheme = {
+  colors: {
+    primary: '#ad0000',
+    secondary: '#f5f5f5',
+    accent: '#0066cc',
+  },
+  spacing: {
+    sidebar: '16rem',
+    header: '4rem',
+  },
+  borderRadius: {
+    default: '0.5rem',
+    large: '1rem',
+  },
+};
+
+<DashboardProvider config={{ theme: customTheme }}>
+  <App />
+</DashboardProvider>;
+```
+
+## 🔄 Migration Guide
+
+### From v0.0.1 to v1.0.0
+
+```jsx
+// Before
+import { Dashboard } from '@integrativedesigndevelopment/dashboard-core';
+
+// After
+import { DashboardProvider } from '@integrativedesigndevelopment/dashboard-core';
+
+// Before
+<Dashboard plugins={plugins} />
+
+// After
+<DashboardProvider config={{ plugins: ['plugin-1', 'plugin-2'] }}>
+  <YourApp />
+</DashboardProvider>
+```
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**Plugin not loading**
+
+```jsx
+// Check plugin registration
+const plugins = get_all_plugins();
+console.log(
+  'Available plugins:',
+  plugins.map((p) => p.id)
+);
+
+// Verify plugin structure
+const plugin = plugins.find((p) => p.id === 'my-plugin');
+console.log('Plugin structure:', plugin);
+```
+
+**State not updating**
+
+```jsx
+// Ensure DashboardProvider wraps your app
+<DashboardProvider>
+  <App />
+</DashboardProvider>;
+
+// Use the hook correctly
+const { state, dispatch } = useDashboard();
+```
+
+**TypeScript errors**
+
+```typescript
+// Extend plugin interface for custom properties
+declare module '@integrativedesigndevelopment/dashboard-core' {
+  interface IDDPlugin {
+    customProperty?: string;
+  }
+}
+```
+
+## 📝 Examples
+
+### Complete Dashboard Setup
+
+```jsx
+import React from 'react';
+import {
+  DashboardProvider,
+  SimpleButton,
+  useDashboard,
+} from '@integrativedesigndevelopment/dashboard-core';
+
+const dashboardConfig = {
+  theme: 'light',
+  plugins: ['Dashboard', 'Content'],
+  features: {
+    notifications: true,
+    metrics: true,
+  },
+};
+
+function Dashboard() {
+  const { plugins, notifications } = useDashboard();
+
+  return (
+    <div className="idd-dashboard-container">
+      <header className="bg-white shadow p-4">
+        <h1>My Dashboard</h1>
+        <span>{notifications.length} notifications</span>
+      </header>
+
+      <main className="flex">
+        <aside className="idd-sidebar p-4">
+          <h2>Plugins</h2>
+          {plugins.map((plugin) => (
+            <div key={plugin.id} className="mb-2">
+              <SimpleButton variant="ghost" size="small">
+                {plugin.name}
+              </SimpleButton>
+            </div>
+          ))}
+        </aside>
+
+        <div className="flex-1 p-6">{/* Main content */}</div>
+      </main>
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <DashboardProvider config={dashboardConfig}>
+      <Dashboard />
+    </DashboardProvider>
+  );
+}
+
+export default App;
+```
+
+### Custom Plugin with Metrics
+
+```jsx
+import React, { useEffect } from 'react';
+import {
+  IDDPlugin,
+  trackCustomMetric,
+  useDashboard,
+} from '@integrativedesigndevelopment/dashboard-core';
+
+function AnalyticsContent() {
+  const { state } = useDashboard();
+
+  useEffect(() => {
+    // Track plugin usage
+    trackCustomMetric('analytics-plugin-view', {
+      timestamp: Date.now(),
+      userId: state.user?.id,
+    });
+  }, [state.user]);
+
+  return (
+    <div className="p-6">
+      <h2>Analytics Dashboard</h2>
+      <div className="grid grid-cols-2 gap-4 mt-4">
+        <div className="bg-white p-4 rounded shadow">
+          <h3>Page Views</h3>
+          <p className="text-2xl font-bold">1,234</p>
+        </div>
+        <div className="bg-white p-4 rounded shadow">
+          <h3>Users</h3>
+          <p className="text-2xl font-bold">567</p>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+const AnalyticsPlugin: IDDPlugin = {
+  id: 'analytics',
+  name: 'Analytics',
+  order: 5,
+  tabs: [
+    {
+      id: 'overview',
+      name: 'Overview',
+      content: <AnalyticsContent />,
+    },
+  ],
+  settings: [
+    {
+      key: 'trackingEnabled',
+      label: 'Enable Tracking',
+      type: 'toggle',
+      defaultValue: true,
+    },
+  ],
+};
+
+export default AnalyticsPlugin;
+```
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/core-improvement`
+3. Make your changes
+4. Add tests for new functionality
+5. Run tests: `npm test`
+6. Submit a pull request
+
+## 📄 License
+
+MIT License - see [LICENSE](../../LICENSE) file for details.
+
+## 🔗 Related Packages
+
+- [@integrativedesigndevelopment/dashboard-auth](../dashboard-auth) - Authentication system
+- [@integrativedesigndevelopment/dashboard-nav](../dashboard-nav) - Navigation components
+- [@integrativedesigndevelopment/dashboard-icons](../dashboard-icons) - Icon library
+
+---
+
+**Need help?** Check out our [documentation](../../docs) or [open an issue](https://dev.azure.com/IntegrativeDesignDevelopment/IDD/_workitems).