@pattern-stack/frontend-patterns 0.0.4 → 0.0.6

package/src/atoms/utils/metric-engine.ts

@@ -0,0 +1,236 @@
+import type { MetricConfig, MetricValue, EntityData, FormatConfig, TrendDataPoint } from '../types';
+
+export class MetricCalculationEngine {
+  static calculateMetric(
+    config: MetricConfig,
+    data: EntityData[],
+    previousData?: EntityData[]
+  ): MetricValue {
+    const currentValue = this.aggregateValue(config, data);
+    const previousValue = previousData ? this.aggregateValue(config, previousData) : undefined;
+    
+    const trend = this.calculateTrend(currentValue, previousValue);
+    const formattedValue = this.formatValue(currentValue, config.format, config.type);
+    
+    const target = typeof config.target === 'function' 
+      ? config.target(data) 
+      : config.target;
+
+    return {
+      current: currentValue,
+      previous: previousValue,
+      trend,
+      target,
+      formattedValue
+    };
+  }
+
+  private static aggregateValue(config: MetricConfig, data: EntityData[]): number {
+    if (!data.length) return 0;
+
+    const values = data
+      .map(item => {
+        const value = this.extractValue(item, config.key);
+        return typeof value === 'number' ? value : 0;
+      })
+      .filter(value => !isNaN(value));
+
+    if (!values.length) return 0;
+
+    switch (config.aggregation || 'sum') {
+      case 'sum':
+        return values.reduce((sum, value) => sum + value, 0);
+      case 'avg':
+        return values.reduce((sum, value) => sum + value, 0) / values.length;
+      case 'count':
+        return values.length;
+      case 'min':
+        return Math.min(...values);
+      case 'max':
+        return Math.max(...values);
+      default:
+        return values.reduce((sum, value) => sum + value, 0);
+    }
+  }
+
+  private static extractValue(item: EntityData, key: string): unknown {
+    return key.split('.').reduce((obj: any, k: string) => obj?.[k], item);
+  }
+
+  private static calculateTrend(current: number, previous?: number): 'up' | 'down' | 'neutral' {
+    if (previous === undefined || previous === 0) return 'neutral';
+    
+    const change = ((current - previous) / Math.abs(previous)) * 100;
+    
+    if (change > 1) return 'up';
+    if (change < -1) return 'down';
+    return 'neutral';
+  }
+
+  private static formatValue(value: number, format?: FormatConfig, type?: string): string {
+    let formatted = value;
+
+    if (format?.decimals !== undefined) {
+      formatted = Number(value.toFixed(format.decimals));
+    }
+
+    let result = formatted.toString();
+
+    if (format?.thousands !== false && Math.abs(formatted) >= 1000) {
+      result = formatted.toLocaleString();
+    }
+
+    switch (type) {
+      case 'currency':
+        result = new Intl.NumberFormat('en-US', {
+          style: 'currency',
+          currency: 'USD',
+          minimumFractionDigits: format?.decimals ?? 2,
+          maximumFractionDigits: format?.decimals ?? 2
+        }).format(formatted);
+        break;
+      case 'percentage':
+        result = `${formatted.toFixed(format?.decimals ?? 1)}%`;
+        break;
+      case 'duration':
+        result = this.formatDuration(formatted);
+        break;
+      case 'ratio':
+        result = `${formatted.toFixed(format?.decimals ?? 2)}:1`;
+        break;
+      default:
+        if (format?.prefix) result = format.prefix + result;
+        if (format?.suffix) result = result + format.suffix;
+    }
+
+    return result;
+  }
+
+  private static formatDuration(minutes: number): string {
+    const hours = Math.floor(minutes / 60);
+    const mins = Math.floor(minutes % 60);
+    
+    if (hours > 0) {
+      return `${hours}h ${mins}m`;
+    }
+    return `${mins}m`;
+  }
+
+  static calculateTrendData(
+    config: MetricConfig,
+    data: EntityData[],
+    dateField: string = 'date',
+    periods: number = 12
+  ): TrendDataPoint[] {
+    const groupedData = this.groupByPeriod(data, dateField);
+    const sortedDates = Object.keys(groupedData).sort();
+    
+    return sortedDates.slice(-periods).map(date => ({
+      date,
+      value: this.aggregateValue(config, groupedData[date]),
+      label: this.formatDateLabel(date)
+    }));
+  }
+
+  private static groupByPeriod(data: EntityData[], dateField: string): Record<string, EntityData[]> {
+    return data.reduce((groups, item) => {
+      const date = this.extractValue(item, dateField);
+      if (!date) return groups;
+      
+      const period = new Date(date as string | number | Date).toISOString().split('T')[0];
+      
+      if (!groups[period]) groups[period] = [];
+      groups[period].push(item);
+      
+      return groups;
+    }, {} as Record<string, EntityData[]>);
+  }
+
+  private static formatDateLabel(dateString: string): string {
+    const date = new Date(dateString);
+    return date.toLocaleDateString('en-US', { 
+      month: 'short', 
+      day: 'numeric' 
+    });
+  }
+
+  static calculateCategoryBreakdown(
+    data: EntityData[],
+    categoryField: string,
+    valueField: string,
+    maxCategories: number = 8
+  ) {
+    const groups = data.reduce((acc, item) => {
+      const category = String(this.extractValue(item, categoryField) || 'Unknown');
+      const value = this.extractValue(item, valueField) || 0;
+      
+      if (!acc[category]) acc[category] = 0;
+      acc[category] += typeof value === 'number' ? value : 0;
+      
+      return acc;
+    }, {} as Record<string, number>);
+
+    const total = Object.values(groups).reduce((sum, value) => sum + value, 0);
+    
+    let categories = Object.entries(groups)
+      .map(([category, value]) => ({
+        category,
+        value,
+        percentage: total > 0 ? (value / total) * 100 : 0
+      }))
+      .sort((a, b) => b.value - a.value);
+
+    if (categories.length > maxCategories) {
+      const topCategories = categories.slice(0, maxCategories - 1);
+      const otherValue = categories.slice(maxCategories - 1)
+        .reduce((sum, cat) => sum + cat.value, 0);
+      
+      topCategories.push({
+        category: 'Other',
+        value: otherValue,
+        percentage: total > 0 ? (otherValue / total) * 100 : 0
+      });
+      
+      categories = topCategories;
+    }
+
+    return categories;
+  }
+
+  static detectInsights(
+    metrics: Record<string, MetricValue>,
+    thresholds: Record<string, { warning: number; critical: number }> = {}
+  ) {
+    const insights = [];
+
+    for (const [key, metric] of Object.entries(metrics)) {
+      const threshold = thresholds[key];
+      
+      if (metric.target && metric.current < metric.target * 0.8) {
+        insights.push({
+          type: 'negative' as const,
+          message: `${key} is significantly below target`,
+          value: metric.current
+        });
+      }
+      
+      if (metric.trend === 'up' && metric.previous && metric.current > metric.previous * 1.2) {
+        insights.push({
+          type: 'positive' as const,
+          message: `${key} showing strong growth`,
+          value: metric.current
+        });
+      }
+      
+      if (threshold && metric.current >= threshold.critical) {
+        insights.push({
+          type: 'negative' as const,
+          message: `${key} has reached critical threshold`,
+          value: metric.current
+        });
+      }
+    }
+
+    return insights.slice(0, 5);
+  }
+}

package/src/atoms/utils/utils.ts

@@ -5,5 +5,7 @@ export function cn(...inputs: ClassValue[]) {
   return twMerge(clsx(inputs))
 }
 
-// Re-export tooltip helpers
-export * from './tooltip-helpers';
+// Re-export utilities
+export * from './tooltip-helpers';
+export * from './metric-engine';
+export { Icon, getIcon, isValidIcon } from './icon-resolver';

package/src/molecules/layout/DashboardWithSidePanel/DashboardWithSidePanel.tsx

@@ -0,0 +1,42 @@
+import React from 'react';
+import { cn } from '../../../atoms/utils/utils';
+
+interface DashboardWithSidePanelProps {
+  /** Main dashboard content */
+  children: React.ReactNode;
+  /** Side panel component to display */
+  sidePanel?: React.ReactNode;
+  /** Whether to show the side panel */
+  showSidePanel?: boolean;
+  /** Side panel width in Tailwind units (e.g., 72, 80) */
+  sidePanelWidth?: number;
+  /** Additional CSS classes */
+  className?: string;
+}
+
+export const DashboardWithSidePanel: React.FC<DashboardWithSidePanelProps> = ({
+  children,
+  sidePanel,
+  showSidePanel = false,
+  sidePanelWidth = 72,
+  className
+}) => {
+  const marginClass = `pr-${sidePanelWidth}`;
+
+  return (
+    <div className={cn('relative h-full', className)}>
+      {/* Main Dashboard Content */}
+      <div 
+        className={cn(
+          'transition-all duration-300',
+          showSidePanel ? marginClass : ''
+        )}
+      >
+        {children}
+      </div>
+
+      {/* Side Panel */}
+      {showSidePanel && sidePanel}
+    </div>
+  );
+};

package/src/molecules/layout/DashboardWithSidePanel/index.ts

@@ -0,0 +1 @@
+export { DashboardWithSidePanel } from './DashboardWithSidePanel';

package/src/molecules/layout/NavigationContext.tsx

@@ -0,0 +1,63 @@
+import React, { createContext, useContext, type ReactNode } from 'react'
+import type { NavigationConfig, NavigationItem } from '../../atoms/types'
+
+interface NavigationContextType {
+  navigation: NavigationConfig
+  setNavigation: (config: NavigationConfig) => void
+}
+
+const NavigationContext = createContext<NavigationContextType | undefined>(undefined)
+
+interface NavigationProviderProps {
+  children: ReactNode
+  initialNavigation?: NavigationConfig
+}
+
+// Default showcase navigation for backwards compatibility
+const defaultShowcaseNavigation: NavigationItem[] = [
+  { value: 'showcase', label: 'Showcase', icon: 'Palette', path: '/showcase', category: 5 },
+  { value: 'admin-dashboard', label: 'Admin Dashboard', icon: 'Shield', path: '/admin/dashboard', category: 2 },
+  { value: 'admin-users', label: 'User Management', icon: 'Users', path: '/admin/users', category: 3 },
+  { value: 'admin-sales', label: 'Sales Dashboard', icon: 'TrendingUp', path: '/admin/sales', category: 4 },
+  { value: 'entity-performance', label: 'Performance Dashboard', icon: 'BarChart3', path: '/entity/performance', category: 6 },
+  { value: 'entity-management', label: 'Entity Management', icon: 'Database', path: '/entity/management', category: 7 },
+  { value: 'entity-template', label: 'Template Example', icon: 'Layout', path: '/entity/template-example', category: 1 }
+]
+
+export const NavigationProvider = ({ children, initialNavigation }: NavigationProviderProps) => {
+  const [navigation, setNavigation] = React.useState<NavigationConfig>(
+    initialNavigation || {
+      items: defaultShowcaseNavigation,
+      showDefaultNavigation: true,
+      defaultExpanded: true
+    }
+  )
+
+  return (
+    <NavigationContext.Provider value={{ navigation, setNavigation }}>
+      {children}
+    </NavigationContext.Provider>
+  )
+}
+
+export const useNavigation = () => {
+  const context = useContext(NavigationContext)
+  if (context === undefined) {
+    throw new Error('useNavigation must be used within a NavigationProvider')
+  }
+  return context
+}
+
+// Helper to get navigation items with fallback
+export const getNavigationItems = (config: NavigationConfig): NavigationItem[] => {
+  if (config.items.length > 0) {
+    return config.items
+  }
+  
+  // Fallback to showcase navigation if no items provided
+  if (config.showDefaultNavigation !== false) {
+    return defaultShowcaseNavigation
+  }
+  
+  return []
+}

package/src/molecules/layout/Sidebar.tsx

@@ -1,23 +1,10 @@
-import React from 'react';
 import { useLocation, useNavigate, useSearchParams } from 'react-router-dom';
-import { cn } from '../../atoms/utils/utils';
+import { cn, Icon } from '../../atoms/utils/utils';
 import { useSidebar } from './SidebarContext';
+import { useNavigation, getNavigationItems } from './NavigationContext';
 import { SidebarButton } from './SidebarButton';
-import { 
-  Palette,
-  Menu,
-  X,
-  Shield,
-  Users
-} from 'lucide-react';
-
-interface SidebarItem {
-  value: string;
-  label: string;
-  icon: React.ReactNode;
-  path: string;
-  category?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
-}
+import { Menu, X } from 'lucide-react';
+import type { NavigationItem } from '../../atoms/types';
 
 interface SidebarProps {
   className?: string;
@@ -25,15 +12,13 @@ interface SidebarProps {
 
 export const Sidebar = ({ className }: SidebarProps) => {
   const { isExpanded, toggleSidebar } = useSidebar();
+  const { navigation } = useNavigation();
   const location = useLocation();
   const navigate = useNavigate();
   const [searchParams] = useSearchParams();
 
-  const items: SidebarItem[] = [
-    { value: 'showcase', label: 'Showcase', icon: <Palette className="w-5 h-5" />, path: '/showcase', category: 5 },
-    { value: 'admin-dashboard', label: 'Admin Dashboard', icon: <Shield className="w-5 h-5" />, path: '/admin/dashboard', category: 2 },
-    { value: 'admin-users', label: 'User Management', icon: <Users className="w-5 h-5" />, path: '/admin/users', category: 3 }
-  ];
+  // Get navigation items from context
+  const items: NavigationItem[] = getNavigationItems(navigation);
 
   const handleNavigation = (path: string) => {
     if (path.includes('?')) {
@@ -100,12 +85,14 @@ export const Sidebar = ({ className }: SidebarProps) => {
           return (
             <SidebarButton
               key={item.value}
-              icon={item.icon}
+              icon={<Icon name={item.icon} className="w-5 h-5" />}
               label={item.label}
               active={isActive}
               category={item.category}
               expanded={isExpanded}
               onClick={() => handleNavigation(item.path)}
+              badge={item.badge}
+              disabled={item.disabled}
             />
           );
         })}

package/src/molecules/layout/SidebarButton/SidebarButton.tsx

@@ -10,6 +10,8 @@ interface SidebarButtonProps {
   expanded?: boolean;
   onClick?: () => void;
   className?: string;
+  badge?: string | number;
+  disabled?: boolean;
 }
 
 export const SidebarButton: React.FC<SidebarButtonProps> = ({
@@ -19,12 +21,15 @@ export const SidebarButton: React.FC<SidebarButtonProps> = ({
   category = 1,
   expanded = false,
   onClick,
-  className
+  className,
+  badge,
+  disabled = false
 }) => {
   return (
     <Button
       variant={active ? "secondary" : "ghost"}
       onClick={onClick}
+      disabled={disabled}
       tooltip={!expanded ? label : undefined}
       className={cn(
         "relative w-full justify-start gap-3 h-12",
@@ -74,8 +79,15 @@ export const SidebarButton: React.FC<SidebarButtonProps> = ({
             {label}
           </span>
           
-          {/* Active indicator dot */}
-          {active && (
+          {/* Badge or Active indicator */}
+          {badge ? (
+            <span className={cn(
+              "px-2 py-0.5 text-xs font-medium rounded-full flex-shrink-0",
+              "bg-primary/10 text-primary"
+            )}>
+              {badge}
+            </span>
+          ) : active && (
             <div className={cn(
               "w-2 h-2 rounded-full flex-shrink-0",
               `bg-category-${category}`
@@ -84,14 +96,24 @@ export const SidebarButton: React.FC<SidebarButtonProps> = ({
         </>
       )}
       
-      {/* Collapsed active indicator */}
-      {!expanded && active && (
+      {/* Collapsed indicators */}
+      {!expanded && (badge || active) && (
         <div className="absolute -top-1 -right-1">
-          <div className={cn(
-            "w-2.5 h-2.5 rounded-full",
-            `bg-category-${category}`,
-            "ring-2 ring-background"
-          )} />
+          {badge ? (
+            <span className={cn(
+              "px-1.5 py-0.5 text-xs font-bold rounded-full",
+              "bg-primary text-primary-foreground",
+              "ring-2 ring-background"
+            )}>
+              {badge}
+            </span>
+          ) : active && (
+            <div className={cn(
+              "w-2.5 h-2.5 rounded-full",
+              `bg-category-${category}`,
+              "ring-2 ring-background"
+            )} />
+          )}
         </div>
       )}
     </Button>

package/src/molecules/layout/index.ts

@@ -1,7 +1,10 @@
 export { PageTemplate, type PageTemplateProps } from './PageTemplate';
 export { ShowcaseSection } from './ShowcaseSection';
 export { AppLayout } from './AppLayout';
+export { DashboardWithSidePanel } from './DashboardWithSidePanel';
 export { SectionHeader } from './SectionHeader';
 export { SidebarButton } from './SidebarButton';
 export { AppHeader } from './AppHeader';
-export { SidebarProvider, useSidebar } from './SidebarContext';
+export { SidebarProvider, useSidebar } from './SidebarContext';
+export { NavigationProvider, useNavigation, getNavigationItems } from './NavigationContext';
+export { Sidebar } from './Sidebar';