# Component Architecture
This document outlines the essential rules for structuring PatternFly components, managing state, and ensuring performance. It is a high-level guide that links to more detailed documentation for specific patterns.
## Related Files
- [**Layout Rules**](../components/layout/README.md) - For page structure and layout patterns.
- [**Table Component Rules**](../components/data-display/table.md) - For table usage, selection, and actions.
- [**Data View Component Rules**](../components/data-display/README.md) - For data view usage.
- [**Styling Rules**](./styling-standards.md) - For CSS and styling approaches.
## 1. Component Composition
### PatternFly-First Approach
Always start with standard PatternFly components and compose them to build complex UIs. Avoid creating custom components when a PatternFly solution already exists.
```jsx
// ✅ Correct: Compose existing PatternFly components
import { Card, CardTitle, CardBody, Button, Content } from '@patternfly/react-core';
const UserCard = ({ user, onEdit }) => (
<Card>
<CardTitle>{user.name}</CardTitle>
<CardBody>
<Content component="p">{user.email}</Content>
<Button variant="secondary" onClick={onEdit}>Edit</Button>
</CardBody>
</Card>
);
```
### Component Hierarchy
Structure your application in a clear hierarchy:
1. **Page Components**: Top-level page structure.
2. **Section Components**: Major page sections, often corresponding to a `PageSection`.
3. **Feature Components**: Components that encapsulate a specific piece of functionality.
4. **PatternFly Components**: The base building blocks from `@patternfly/react-core`.
### Data Display
For displaying labeled data or key-value pairs, always use PatternFly's `DescriptionList` components for clarity and accessibility.
- **See**: [DescriptionList Documentation](https://www.patternfly.org/components/description-list)
## 2. State Management
### Local vs. Shared State
- **Local State (`useState`)**: Use for component-specific UI state like form inputs or toggles.
- **Shared State (`useContext`)**: Use for state that needs to be accessed by multiple components in a tree.
- **Complex State (`useReducer`)**: Use for state with complex update logic.
Keep state as local as possible and only lift it when necessary.
## 3. Common Patterns
For detailed guidance and code examples on common UI patterns, refer to the specific documentation:
- **Selectable Tables**: See [Table Component Rules](../components/data-display/table.md).
- **Dropdown Actions**: See the [Dropdown Documentation](https://www.patternfly.org/components/menus/dropdown).
- **Toolbar with Filters**: See the [Toolbar Documentation](https://www.patternfly.org/components/toolbar).
## 4. Error Handling and Data States
Always account for different data states in your components:
- ✅ **Loading State**: Show a `Spinner` or `Skeleton` while data is fetching.
- ✅ **Error State**: Display a clear error message, often using `EmptyState`.
- ✅ **Empty State**: Provide a message when there is no data to display.
```jsx
// ✅ Required: Handle all data states
import { EmptyState, Spinner } from '@patternfly/react-core';
if (isLoading) return <Spinner />;
if (error) return <EmptyState titleText="Error" icon={ErrorIcon} />;
if (!data?.length) return <EmptyState titleText="No results found" />;
return <MyComponent data={data} />;
```
## 5. Performance
- **Memoization**: Use `React.memo`, `useCallback`, and `useMemo` to prevent unnecessary re-renders, especially in lists.
- **Virtualization**: For long lists or tables (1000+ rows), use a virtualization library to ensure performance.
- **Lazy Loading**: Use `React.lazy` and `Suspense` to code-split parts of your application and load them on demand.
## 6. Testing
- **Focus on Behavior**: Test what the user can do (e.g., clicking a button, filling a form), not component implementation details.
- **Accessibility**: Always include tests for ARIA attributes and keyboard navigation.
- **Don't Test PatternFly**: Trust that PatternFly components are already tested. Focus your tests on your application's logic.
## Quick Reference
- [**PatternFly Components**](https://www.patternfly.org/components) - Official component documentation
- [**React Patterns**](https://reactpatterns.com/) - Common React patterns and best practices
- [**Testing Library**](https://testing-library.com/) - Component testing best practices
