@pattern-stack/frontend-patterns 0.0.3 → 0.0.5

package/package.json

@@ -2,7 +2,7 @@
   "name": "@pattern-stack/frontend-patterns",
   "description": "Production-ready React frontend template with atomic architecture patterns. Build ultra-lean applications by importing shared UI foundation patterns.",
   "private": false,
-  "version": "0.0.3",
+  "version": "0.0.5",
   "keywords": [
     "react",
     "typescript",
@@ -33,16 +33,18 @@
       "import": "./dist/index.es.js",
       "require": "./dist/index.js"
     },
-    "./styles": "./dist/frontend-patterns.css"
+    "./styles": "./dist/frontend-patterns.css",
+    "./src/*": "./src/*"
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "type": "module",
   "scripts": {
     "dev": "vite",
     "build": "tsc -b && vite build",
-    "build:lib": "npm run clean && vite build --mode library && tsc -p tsconfig.lib.json",
+    "build:lib": "npm run clean && vite build --mode library",
     "clean": "rm -rf dist",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
@@ -100,9 +102,12 @@
     "@vitejs/plugin-react": "^4.4.1",
     "@vitest/coverage-v8": "^3.2.1",
     "autoprefixer": "^10.4.21",
+    "concurrently": "^9.1.2",
+    "cors": "^2.8.5",
     "eslint": "^9.25.0",
     "eslint-plugin-react-hooks": "^5.2.0",
     "eslint-plugin-react-refresh": "^0.4.19",
+    "express": "^5.1.0",
     "globals": "^16.0.0",
     "jsdom": "^26.1.0",
     "postcss": "^8.5.3",
@@ -113,4 +118,4 @@
     "vite": "^6.3.5",
     "vitest": "^3.2.1"
   }
-}
+}

package/src/App.css

@@ -0,0 +1,42 @@
+#root {
+  max-width: 1280px;
+  margin: 0 auto;
+  padding: 2rem;
+  text-align: center;
+}
+
+.logo {
+  height: 6em;
+  padding: 1.5em;
+  will-change: filter;
+  transition: filter 300ms;
+}
+.logo:hover {
+  filter: drop-shadow(0 0 2em #646cffaa);
+}
+.logo.react:hover {
+  filter: drop-shadow(0 0 2em #61dafbaa);
+}
+
+@keyframes logo-spin {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  a:nth-of-type(2) .logo {
+    animation: logo-spin infinite 20s linear;
+  }
+}
+
+.card {
+  padding: 2em;
+}
+
+.read-the-docs {
+  color: #888;
+}

package/src/App.tsx

@@ -0,0 +1,64 @@
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+
+// Atoms
+import { ErrorBoundary } from './atoms/ui';
+
+// Features
+import { ProtectedRoute } from './features/auth';
+
+// Organisms  
+import { AppLayout } from './molecules/layout/AppLayout';
+import { ComponentShowcasePage } from './organisms/showcase';
+
+// Pages
+import { 
+  ComponentShowcase, 
+  AdminDashboardShowcase, 
+  AdminCRUDShowcase, 
+  AdminDetailShowcase,
+  SalesPerformanceDashboard,
+  EntityPerformanceShowcase,
+  EntityManagementShowcase
+} from './pages';
+import { EntityTemplateExample } from './pages/EntityTemplateExample';
+
+function App() {
+  return (
+    <ErrorBoundary>
+      <BrowserRouter>
+        <Routes>
+          <Route path="/" element={
+            <ProtectedRoute>
+              <AppLayout />
+            </ProtectedRoute>
+          }>
+            {/* Default to Component Showcase */}
+            <Route index element={<ErrorBoundary><ComponentShowcasePage /></ErrorBoundary>} />
+            
+            {/* Component Showcase - Complete with Navigation/Forms/Feedback */}
+            <Route path="showcase" element={<ErrorBoundary><ComponentShowcasePage /></ErrorBoundary>} />
+            
+            {/* Template-driven Showcase (alternative version) */}
+            <Route path="showcase-alt" element={<ErrorBoundary><ComponentShowcase /></ErrorBoundary>} />
+            
+            {/* Admin Template Showcases */}
+            <Route path="admin/dashboard" element={<ErrorBoundary><AdminDashboardShowcase /></ErrorBoundary>} />
+            <Route path="admin/users" element={<ErrorBoundary><AdminCRUDShowcase /></ErrorBoundary>} />
+            <Route path="admin/user/:id" element={<ErrorBoundary><AdminDetailShowcase /></ErrorBoundary>} />
+            <Route path="admin/sales" element={<ErrorBoundary><SalesPerformanceDashboard /></ErrorBoundary>} />
+            
+            {/* Entity Template Showcases */}
+            <Route path="entity/performance" element={<ErrorBoundary><EntityPerformanceShowcase /></ErrorBoundary>} />
+            <Route path="entity/management" element={<ErrorBoundary><EntityManagementShowcase /></ErrorBoundary>} />
+            <Route path="entity/template-example" element={<ErrorBoundary><EntityTemplateExample /></ErrorBoundary>} />
+            
+            {/* Fallback */}
+            <Route path="*" element={<ErrorBoundary><ComponentShowcasePage /></ErrorBoundary>} />
+          </Route>
+        </Routes>
+      </BrowserRouter>
+    </ErrorBoundary>
+  );
+}
+
+export default App;

package/src/__tests__/README.md

@@ -0,0 +1,221 @@
+# Frontend Testing Strategy
+
+> Atomic design testing that mirrors your backend testing architecture
+
+## 🏗️ Testing Architecture
+
+Our frontend tests follow the **same atomic structure** as your backend tests:
+
+```
+src/__tests__/
+├── atoms/              # Unit tests (like backend atoms/)
+│   ├── ui/            # UI component tests
+│   ├── business/      # Business component tests  
+│   ├── hooks/         # React hooks tests
+│   ├── utils/         # Utility function tests
+│   └── services/      # API client tests
+├── molecules/         # Component integration tests
+│   ├── forms/         # Form component tests
+│   ├── layout/        # Layout component tests
+│   └── navigation/    # Navigation tests
+├── organisms/         # Page/complex component tests
+│   └── showcase/      # Full page tests
+├── features/          # Feature integration tests
+│   └── auth/          # Auth system tests
+├── setup.ts           # Test setup (like conftest.py)
+└── utils.tsx          # Test utilities (like pytest fixtures)
+```
+
+## 🧪 Testing Stack
+
+**Framework**: Vitest (Vite-native, fast)
+**React Testing**: @testing-library/react
+**User Interaction**: @testing-library/user-event  
+**Environment**: jsdom (browser simulation)
+**Assertions**: jest-dom matchers
+
+## 📋 Test Commands
+
+```bash
+# Run all tests
+npm run test
+
+# Run with UI (visual test runner)
+npm run test:ui
+
+# Run once (CI mode)
+npm run test:run
+
+# Watch mode (development)
+npm run test:watch
+
+# Coverage report
+npm run test:coverage
+
+# Test by atomic level (like backend)
+npm run test:atoms       # Unit tests
+npm run test:molecules   # Component integration
+npm run test:organisms   # Page tests  
+npm run test:features    # Feature integration
+```
+
+## 🎯 Testing Patterns
+
+### Atoms (Unit Tests)
+```typescript
+// UI Components
+describe('Button (Atom)', () => {
+  it('renders with correct variant styles', () => {
+    render(<Button variant="primary">Click me</Button>)
+    expect(screen.getByRole('button')).toHaveClass('bg-primary')
+  })
+})
+
+// Hooks
+describe('useApi (Atom)', () => {
+  it('handles API calls correctly', async () => {
+    const { result } = renderHook(() => useApiQuery(['test'], mockFn))
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+  })
+})
+
+// Utils
+describe('cn utility (Atom)', () => {
+  it('merges classes correctly', () => {
+    expect(cn('px-4', 'py-2')).toBe('px-4 py-2')
+  })
+})
+```
+
+### Molecules (Component Integration)
+```typescript
+describe('AppHeader (Molecule)', () => {
+  it('integrates auth, navigation, and UI atoms', () => {
+    render(<AppHeader />)
+    expect(screen.getByRole('banner')).toBeInTheDocument()
+    expect(screen.getByTestId('user-menu')).toBeInTheDocument()
+  })
+})
+```
+
+### Organisms (Page Tests)
+```typescript
+describe('ComponentShowcasePage (Organism)', () => {
+  it('renders complete page with all sections', () => {
+    render(<ComponentShowcasePage />)
+    expect(screen.getByRole('main')).toBeInTheDocument()
+    // Test full page functionality
+  })
+})
+```
+
+### Features (Integration Tests)
+```typescript
+describe('useAuth (Feature)', () => {
+  it('handles complete auth flow', async () => {
+    const { result } = renderHook(() => useAuth())
+    await act(() => result.current.login(credentials))
+    expect(result.current.isAuthenticated).toBe(true)
+  })
+})
+```
+
+## 🛠️ Test Utilities
+
+### Setup (`setup.ts`)
+- Global test configuration
+- Mock browser APIs
+- Environment setup
+- Like your `conftest.py`
+
+### Utils (`utils.tsx`)
+- Custom render with providers
+- Mock factories (users, API clients)
+- Test helpers and fixtures
+- Like your pytest fixtures
+
+### Example Usage
+```typescript
+import { render, createMockUser, createMockApiClient } from '../utils'
+
+describe('MyComponent', () => {
+  it('works with test utilities', () => {
+    const mockUser = createMockUser({ name: 'Test User' })
+    const mockApi = createMockApiClient()
+    
+    render(<MyComponent />, {
+      initialRoute: '/dashboard',
+      queryClient: new QueryClient()
+    })
+  })
+})
+```
+
+## 🎨 Design System Testing
+
+Our tests enforce design system compliance:
+
+```typescript
+it('uses design system classes only', () => {
+  render(<Component />)
+  const element = screen.getByRole('button')
+  
+  // ✅ Should use design system
+  expect(element).toHaveClass('bg-primary')
+  
+  // ❌ Should NOT use hardcoded colors
+  expect(element.className).not.toMatch(/bg-blue-\d+/)
+})
+```
+
+## 📊 Coverage Goals
+
+- **Atoms**: 90%+ (pure functions, UI components)
+- **Molecules**: 80%+ (component integration)
+- **Organisms**: 70%+ (complex pages)
+- **Features**: 85%+ (business logic)
+
+## 🔄 CI/CD Integration
+
+Tests run in pre-commit hooks:
+```bash
+npm run pre-commit  # style:check + test:run + build
+```
+
+## 🚀 Running Tests
+
+```bash
+# Development workflow
+npm run test:watch        # Watch mode while coding
+
+# Before committing  
+npm run test:run          # Full test suite
+npm run test:coverage     # Check coverage
+
+# Debugging specific areas
+npm run test:atoms        # Just unit tests
+npm run test:features     # Just integration tests
+
+# Visual debugging
+npm run test:ui           # Vitest UI runner
+```
+
+## 🎯 Best Practices
+
+1. **Mirror Backend Structure**: Tests follow atomic design
+2. **Design System Compliance**: Test CSS class usage
+3. **Integration Focus**: Test component interactions
+4. **User-Centric**: Test user workflows, not implementation
+5. **Mock External Dependencies**: API calls, localStorage, etc.
+6. **Accessibility**: Test keyboard navigation, ARIA attributes
+
+## 🔧 Configuration
+
+- **vitest.config.ts**: Main test configuration
+- **setup.ts**: Global test setup and mocks
+- **utils.tsx**: Reusable test utilities and providers
+- **package.json**: Test scripts and atomic-level commands
+
+---
+
+**Result**: Frontend testing that mirrors your backend's atomic architecture with comprehensive coverage and design system enforcement! 🧪⚛️

package/src/__tests__/atoms/hooks/simple-hooks.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect } from 'vitest'
+import { renderHook } from '@testing-library/react'
+import { useState } from 'react'
+
+describe('Simple Hook Tests (Example)', () => {
+  it('useState hook works correctly', () => {
+    const { result } = renderHook(() => useState(0))
+    
+    const [count, setCount] = result.current
+    expect(count).toBe(0)
+    
+    // Test that hook function is returned
+    expect(typeof setCount).toBe('function')
+  })
+
+  it('useEffect-like behavior can be tested', () => {
+    const { result, rerender } = renderHook(
+      ({ initialValue }) => useState(initialValue),
+      { initialProps: { initialValue: 10 } }
+    )
+
+    expect(result.current[0]).toBe(10)
+
+    // Test re-render with new props
+    rerender({ initialValue: 20 })
+    // Note: useState doesn't re-initialize on prop changes, this is just testing the pattern
+    expect(result.current[0]).toBe(10) // Still 10 because useState doesn't re-init
+  })
+
+  it('custom hook pattern testing', () => {
+    const useCounter = (initial = 0) => {
+      const [count, setCount] = useState(initial)
+      const increment = () => setCount(c => c + 1)
+      const decrement = () => setCount(c => c - 1)
+      return { count, increment, decrement }
+    }
+
+    const { result } = renderHook(() => useCounter(5))
+
+    expect(result.current.count).toBe(5)
+    expect(typeof result.current.increment).toBe('function')
+    expect(typeof result.current.decrement).toBe('function')
+  })
+})

package/src/__tests__/atoms/ui/button.test.tsx

@@ -0,0 +1,68 @@
+import React from 'react'
+import { describe, it, expect } from 'vitest'
+import { render, screen, userEvent } from '../../utils'
+import { Button } from '../../../atoms/ui/button'
+
+describe('Button (Atom)', () => {
+  it('renders with default variant', () => {
+    render(<Button>Click me</Button>)
+    const button = screen.getByRole('button', { name: /click me/i })
+    expect(button).toBeInTheDocument()
+    // The button uses gradient, so check for primary color reference
+    expect(button.className).toContain('from-primary')
+  })
+
+  it('renders with different variants', () => {
+    const { rerender } = render(<Button variant="secondary">Secondary</Button>)
+    expect(screen.getByRole('button')).toHaveClass('bg-gray-100')
+
+    rerender(<Button variant="destructive">Destructive</Button>)
+    expect(screen.getByRole('button').className).toContain('from-destructive')
+  })
+
+  it('renders with different sizes', () => {
+    const { rerender } = render(<Button size="sm">Small</Button>)
+    expect(screen.getByRole('button')).toHaveClass('h-9')
+
+    rerender(<Button size="lg">Large</Button>)
+    expect(screen.getByRole('button')).toHaveClass('h-12')
+  })
+
+  it('handles click events', async () => {
+    const user = userEvent.setup()
+    const handleClick = vi.fn()
+    
+    render(<Button onClick={handleClick}>Click me</Button>)
+    
+    await user.click(screen.getByRole('button'))
+    expect(handleClick).toHaveBeenCalledOnce()
+  })
+
+  it('is disabled when disabled prop is true', () => {
+    render(<Button disabled>Disabled</Button>)
+    const button = screen.getByRole('button')
+    expect(button).toBeDisabled()
+    expect(button).toHaveClass('disabled:pointer-events-none')
+  })
+
+  it('renders as child component when asChild is true', () => {
+    render(
+      <Button asChild>
+        <a href="/test">Link button</a>
+      </Button>
+    )
+    
+    const link = screen.getByRole('link')
+    expect(link).toBeInTheDocument()
+    expect(link.className).toContain('from-primary')
+    expect(link).toHaveAttribute('href', '/test')
+  })
+
+  it('forwards ref correctly', () => {
+    const ref = React.createRef<HTMLButtonElement>()
+    render(<Button ref={ref}>Button</Button>)
+    
+    expect(ref.current).toBeInstanceOf(HTMLButtonElement)
+    expect(ref.current).toHaveTextContent('Button')
+  })
+})

package/src/__tests__/atoms/utils/simple.test.ts

@@ -0,0 +1,18 @@
+import { describe, it, expect } from 'vitest'
+
+describe('Simple Test (Example)', () => {
+  it('basic arithmetic works', () => {
+    expect(2 + 2).toBe(4)
+  })
+
+  it('string manipulation works', () => {
+    const str = 'hello world'
+    expect(str.toUpperCase()).toBe('HELLO WORLD')
+  })
+
+  it('array operations work', () => {
+    const arr = [1, 2, 3]
+    expect(arr.length).toBe(3)
+    expect(arr.includes(2)).toBe(true)
+  })
+})

package/src/__tests__/atoms/utils/utils.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect } from 'vitest'
+import { cn } from '../../../atoms/utils/utils'
+
+describe('Utils (Atoms)', () => {
+  describe('cn (className utility)', () => {
+    it('merges class names correctly', () => {
+      const result = cn('px-4 py-2', 'bg-blue-500')
+      expect(result).toBe('px-4 py-2 bg-blue-500')
+    })
+
+    it('handles conditional classes', () => {
+      const isActive = true
+      const isDisabled = false
+      
+      const result = cn(
+        'base-class',
+        isActive && 'active-class',
+        isDisabled && 'disabled-class'
+      )
+      
+      expect(result).toBe('base-class active-class')
+    })
+
+    it('resolves conflicting Tailwind classes', () => {
+      // tailwind-merge should resolve conflicts
+      const result = cn('px-2 px-4') // px-4 should win
+      expect(result).toBe('px-4')
+    })
+
+    it('handles arrays of classes', () => {
+      const result = cn(['px-4', 'py-2'], ['bg-blue-500', 'text-white'])
+      expect(result).toBe('px-4 py-2 bg-blue-500 text-white')
+    })
+
+    it('handles object syntax', () => {
+      const result = cn({
+        'px-4': true,
+        'py-2': true,
+        'bg-red-500': false,
+        'bg-blue-500': true,
+      })
+      expect(result).toBe('px-4 py-2 bg-blue-500')
+    })
+
+    it('handles undefined and null values', () => {
+      const result = cn('px-4', undefined, null, 'py-2')
+      expect(result).toBe('px-4 py-2')
+    })
+
+    it('handles empty strings', () => {
+      const result = cn('', 'px-4', '', 'py-2')
+      expect(result).toBe('px-4 py-2')
+    })
+
+    it('maintains design system classes', () => {
+      // Test that design system classes are preserved
+      const result = cn('bg-primary text-primary-foreground', 'hover:bg-primary-hover')
+      expect(result).toBe('bg-primary text-primary-foreground hover:bg-primary-hover')
+    })
+
+    it('works with status classes', () => {
+      const status = 'success'
+      const result = cn(
+        'base-class',
+        status === 'success' && 'status-success',
+        status === 'error' && 'status-error'
+      )
+      expect(result).toBe('base-class status-success')
+    })
+
+    it('works with category classes', () => {
+      const category = 2
+      const result = cn('base-class', `category-${category}`)
+      expect(result).toBe('base-class category-2')
+    })
+  })
+})

package/src/__tests__/features/auth/simple-auth.test.tsx

@@ -0,0 +1,40 @@
+import React from 'react'
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '../../utils'
+
+// Simple auth component for testing
+const AuthStatus = ({ isAuthenticated }: { isAuthenticated: boolean }) => (
+  <div>
+    {isAuthenticated ? (
+      <span data-testid="authenticated">User is logged in</span>
+    ) : (
+      <span data-testid="not-authenticated">Please log in</span>
+    )}
+  </div>
+)
+
+describe('Auth Components (Feature)', () => {
+  it('displays authenticated state correctly', () => {
+    render(<AuthStatus isAuthenticated={true} />)
+    
+    expect(screen.getByTestId('authenticated')).toBeInTheDocument()
+    expect(screen.getByText('User is logged in')).toBeInTheDocument()
+  })
+
+  it('displays unauthenticated state correctly', () => {
+    render(<AuthStatus isAuthenticated={false} />)
+    
+    expect(screen.getByTestId('not-authenticated')).toBeInTheDocument()
+    expect(screen.getByText('Please log in')).toBeInTheDocument()
+  })
+
+  it('toggles between states correctly', () => {
+    const { rerender } = render(<AuthStatus isAuthenticated={false} />)
+    
+    expect(screen.getByText('Please log in')).toBeInTheDocument()
+    
+    rerender(<AuthStatus isAuthenticated={true} />)
+    
+    expect(screen.getByText('User is logged in')).toBeInTheDocument()
+  })
+})