mirror of
https://github.com/johndoe6345789/low-code-react-app-b.git
synced 2026-04-25 06:04:54 +00:00
332 lines
8.9 KiB
Markdown
332 lines
8.9 KiB
Markdown
# Component Dependency Map
|
||
|
||
This document visualizes how components are composed in the atomic structure.
|
||
|
||
## App Header Composition
|
||
|
||
```
|
||
AppHeader (organism)
|
||
├── NavigationMenu (organism)
|
||
│ ├── Sheet (shadcn)
|
||
│ ├── NavigationGroupHeader (molecule)
|
||
│ │ └── CaretDown icon
|
||
│ └── NavigationItem (molecule)
|
||
│ ├── Icon
|
||
│ ├── Label
|
||
│ └── Badge (shadcn)
|
||
├── AppBranding (molecule)
|
||
│ ├── AppLogo (atom)
|
||
│ │ └── Code icon
|
||
│ └── Title + Subtitle text
|
||
├── SaveIndicator (molecule)
|
||
│ ├── StatusIcon (atom)
|
||
│ │ ├── CheckCircle icon (saved)
|
||
│ │ └── CloudCheck icon (synced)
|
||
│ └── Time text
|
||
├── ProjectManager (feature)
|
||
└── ToolbarActions (organism)
|
||
└── ToolbarButton (molecule) × 5
|
||
├── Button (shadcn)
|
||
└── Tooltip (shadcn)
|
||
```
|
||
|
||
## Page Header Composition
|
||
|
||
```
|
||
PageHeader (organism)
|
||
└── PageHeaderContent (molecule)
|
||
├── TabIcon (atom)
|
||
│ └── Icon with gradient wrapper
|
||
├── Title text
|
||
└── Description text
|
||
```
|
||
|
||
## Navigation Menu Composition
|
||
|
||
```
|
||
NavigationMenu (organism)
|
||
├── Sheet (shadcn)
|
||
│ ├── SheetTrigger
|
||
│ │ └── Button with List icon
|
||
│ └── SheetContent
|
||
│ ├── SheetHeader with title
|
||
│ ├── Expand/Collapse buttons
|
||
│ └── ScrollArea (shadcn)
|
||
│ └── Collapsible (shadcn) × N groups
|
||
│ ├── NavigationGroupHeader (molecule)
|
||
│ │ ├── CaretDown icon
|
||
│ │ ├── Group label
|
||
│ │ └── Item count
|
||
│ └── CollapsibleContent
|
||
│ └── NavigationItem (molecule) × N
|
||
│ ├── Icon
|
||
│ ├── Label
|
||
│ └── Badge (optional)
|
||
```
|
||
|
||
## Feature Component Examples
|
||
|
||
### Dashboard Stats Grid
|
||
```
|
||
ProjectDashboard (feature)
|
||
└── Grid of StatCard (molecule) × N
|
||
├── IconWrapper (atom)
|
||
│ └── Feature icon
|
||
├── Label text
|
||
└── Value text
|
||
```
|
||
|
||
### Empty States
|
||
```
|
||
EmptyState (molecule)
|
||
├── EmptyStateIcon (atom)
|
||
│ └── Icon with gradient background
|
||
├── Title text
|
||
├── Description text
|
||
└── Action button (optional)
|
||
```
|
||
|
||
### Loading States
|
||
```
|
||
LoadingState (molecule)
|
||
├── LoadingSpinner (atom)
|
||
│ └── Animated spinner
|
||
└── Message text
|
||
```
|
||
|
||
## Component Import Graph
|
||
|
||
```
|
||
App.tsx
|
||
├── imports organisms
|
||
│ ├── AppHeader
|
||
│ │ ├── imports molecules
|
||
│ │ │ ├── AppBranding
|
||
│ │ │ ├── SaveIndicator
|
||
│ │ │ └── ToolbarButton
|
||
│ │ └── imports atoms
|
||
│ │ ├── AppLogo
|
||
│ │ ├── StatusIcon
|
||
│ │ └── ErrorBadge
|
||
│ ├── PageHeader
|
||
│ │ └── imports molecules
|
||
│ │ └── PageHeaderContent
|
||
│ │ └── imports atoms
|
||
│ │ └── TabIcon
|
||
│ └── NavigationMenu
|
||
│ ├── imports molecules
|
||
│ │ ├── NavigationGroupHeader
|
||
│ │ └── NavigationItem
|
||
│ └── imports config
|
||
│ └── navigation-config.tsx
|
||
└── imports features
|
||
├── CodeEditor
|
||
├── ModelDesigner
|
||
├── ProjectDashboard
|
||
└── ... (more features)
|
||
```
|
||
|
||
## Atomic Levels Quick Reference
|
||
|
||
### Level 1: Atoms (7 components)
|
||
- `AppLogo` - Application logo icon
|
||
- `TabIcon` - Icon with styling variants
|
||
- `StatusIcon` - Status indicator (saved/synced)
|
||
- `ErrorBadge` - Badge showing error count
|
||
- `IconWrapper` - Styled icon wrapper
|
||
- `LoadingSpinner` - Animated loading spinner
|
||
- `EmptyStateIcon` - Large icon for empty states
|
||
|
||
### Level 2: Molecules (10 components)
|
||
- `SaveIndicator` - Shows save status with time
|
||
- `AppBranding` - Logo + app name + tagline
|
||
- `PageHeaderContent` - Page title with icon and description
|
||
- `ToolbarButton` - Button with tooltip
|
||
- `NavigationItem` - Navigation link with badge
|
||
- `NavigationGroupHeader` - Collapsible group header
|
||
- `EmptyState` - Empty state with icon, title, description
|
||
- `LoadingState` - Loading indicator with message
|
||
- `StatCard` - Statistic card with icon and value
|
||
- `LabelWithBadge` - Label with optional badge
|
||
|
||
### Level 3: Organisms (4 components)
|
||
- `NavigationMenu` - Complete navigation sidebar
|
||
- `PageHeader` - Page header with context
|
||
- `ToolbarActions` - Toolbar with multiple buttons
|
||
- `AppHeader` - Complete application header
|
||
|
||
### Level 4: Features (20+ components)
|
||
See `/components` directory for full list of feature components.
|
||
|
||
## Data Flow Example: Save Indicator
|
||
|
||
```
|
||
User makes change
|
||
↓
|
||
App.tsx updates KV store
|
||
↓
|
||
setLastSaved(Date.now())
|
||
↓
|
||
AppHeader receives lastSaved prop
|
||
↓
|
||
SaveIndicator (molecule) receives lastSaved
|
||
↓
|
||
Calculates isRecent = (now - lastSaved < 3s)
|
||
↓
|
||
Renders StatusIcon (atom) with type based on isRecent
|
||
↓
|
||
StatusIcon renders CheckCircle (recent) or CloudCheck (older)
|
||
```
|
||
|
||
## Styling Patterns
|
||
|
||
### Gradients
|
||
```css
|
||
/* Used in: AppLogo, TabIcon, EmptyStateIcon */
|
||
.gradient {
|
||
@apply bg-gradient-to-br from-primary to-accent;
|
||
}
|
||
|
||
.gradient-muted {
|
||
@apply bg-gradient-to-br from-muted to-muted/50;
|
||
}
|
||
|
||
.gradient-subtle {
|
||
@apply bg-gradient-to-br from-primary/20 to-accent/20;
|
||
}
|
||
```
|
||
|
||
### Responsive Sizing
|
||
```css
|
||
/* Mobile-first approach used throughout */
|
||
.text-base sm:text-xl /* Headings scale up on larger screens */
|
||
.w-8 sm:w-10 /* Icons grow on larger screens */
|
||
.gap-2 sm:gap-3 /* Spacing increases on larger screens */
|
||
.hidden sm:block /* Show on larger screens only */
|
||
.hidden sm:flex /* Show as flex on larger screens */
|
||
```
|
||
|
||
### Icon Sizes
|
||
```tsx
|
||
// Consistent icon sizing across components
|
||
<Icon size={14} /> // Badges, small UI elements
|
||
<Icon size={16} /> // Toolbar buttons, navigation items
|
||
<Icon size={18} /> // Standard buttons
|
||
<Icon size={20} /> // Logo, prominent buttons
|
||
<Icon size={24} /> // Page headers
|
||
```
|
||
|
||
## Testing Strategy
|
||
|
||
### Unit Tests (Atoms)
|
||
Test individual atoms in isolation:
|
||
```typescript
|
||
describe('StatusIcon', () => {
|
||
it('renders CheckCircle when type is saved', () => {
|
||
render(<StatusIcon type="saved" />)
|
||
expect(screen.getByTestId('check-circle')).toBeInTheDocument()
|
||
})
|
||
})
|
||
```
|
||
|
||
### Integration Tests (Molecules)
|
||
Test molecule composition:
|
||
```typescript
|
||
describe('SaveIndicator', () => {
|
||
it('shows "Saved" text when recently saved', () => {
|
||
const lastSaved = Date.now() - 1000
|
||
render(<SaveIndicator lastSaved={lastSaved} />)
|
||
expect(screen.getByText('Saved')).toBeInTheDocument()
|
||
})
|
||
})
|
||
```
|
||
|
||
### E2E Tests (Organisms)
|
||
Test complete user flows:
|
||
```typescript
|
||
describe('NavigationMenu', () => {
|
||
it('navigates to code editor when item clicked', () => {
|
||
render(<NavigationMenu {...props} />)
|
||
userEvent.click(screen.getByText('Code Editor'))
|
||
expect(onTabChange).toHaveBeenCalledWith('code')
|
||
})
|
||
})
|
||
```
|
||
|
||
## Performance Considerations
|
||
|
||
### Memoization Strategy
|
||
```typescript
|
||
// Atoms: Usually pure, no memo needed
|
||
export function AppLogo() { ... }
|
||
|
||
// Molecules: Memo when props are complex
|
||
export const SaveIndicator = memo(({ lastSaved }) => { ... })
|
||
|
||
// Organisms: Always memo to prevent re-renders
|
||
export const NavigationMenu = memo(({ activeTab, ... }) => { ... })
|
||
```
|
||
|
||
### Code Splitting
|
||
```typescript
|
||
// Feature components are lazy-loaded
|
||
const CodeEditor = lazy(() => import('@/components/CodeEditor'))
|
||
const ModelDesigner = lazy(() => import('@/components/ModelDesigner'))
|
||
|
||
// Atoms and molecules are NOT lazy-loaded (too small, used everywhere)
|
||
```
|
||
|
||
## Accessibility Patterns
|
||
|
||
### Keyboard Navigation
|
||
```tsx
|
||
// All interactive elements support keyboard
|
||
<button
|
||
onClick={handleClick}
|
||
onKeyDown={(e) => e.key === 'Enter' && handleClick()}
|
||
aria-label="Descriptive label"
|
||
>
|
||
```
|
||
|
||
### Screen Reader Support
|
||
```tsx
|
||
// Icons have descriptive labels
|
||
<Icon aria-label="Loading" />
|
||
|
||
// Loading states announce
|
||
<div role="status" aria-live="polite">Loading...</div>
|
||
|
||
// Error badges announce count
|
||
<Badge aria-label={`${count} errors`}>{count}</Badge>
|
||
```
|
||
|
||
### Focus Management
|
||
```tsx
|
||
// Dialogs trap focus
|
||
<Dialog>...</Dialog>
|
||
|
||
// Navigation preserves focus
|
||
<Sheet>...</Sheet>
|
||
|
||
// Tooltips are keyboard accessible
|
||
<Tooltip>...</Tooltip>
|
||
```
|
||
|
||
## Future Enhancements
|
||
|
||
### Potential New Atoms
|
||
- `StatusDot` - Colored status indicator dot
|
||
- `AvatarInitials` - User initials in circle
|
||
- `KeyboardKey` - Styled keyboard key indicator
|
||
|
||
### Potential New Molecules
|
||
- `SearchInput` - Search input with icon and clear button
|
||
- `FileIcon` - File type icon with extension
|
||
- `Breadcrumbs` - Navigation breadcrumb trail
|
||
- `ActionMenu` - Dropdown menu with actions
|
||
|
||
### Potential New Organisms
|
||
- `CommandPalette` - Full command palette interface
|
||
- `QuickAccessToolbar` - Customizable quick actions
|
||
- `NotificationCenter` - Notification list and management
|