239 lines
8.7 KiB
Markdown
239 lines
8.7 KiB
Markdown
# Frontend Component Organization
|
|
|
|
This document describes the organized structure of the frontend codebase, implemented to improve maintainability as the application grows.
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
frontend/src/
|
|
├── api/ # API client functions
|
|
│ ├── auth.js # Authentication endpoints
|
|
│ ├── axios.js # Axios instance with interceptors
|
|
│ ├── list.js # Grocery list endpoints
|
|
│ └── users.js # User management endpoints
|
|
│
|
|
├── components/ # React components (organized by function)
|
|
│ ├── common/ # Reusable UI components
|
|
│ │ ├── ErrorMessage.jsx
|
|
│ │ ├── FloatingActionButton.jsx
|
|
│ │ ├── FormInput.jsx
|
|
│ │ ├── SortDropdown.jsx
|
|
│ │ ├── UserRoleCard.jsx
|
|
│ │ └── index.js # Barrel exports
|
|
│ │
|
|
│ ├── modals/ # All modal/dialog components
|
|
│ │ ├── AddImageModal.jsx
|
|
│ │ ├── AddItemWithDetailsModal.jsx
|
|
│ │ ├── ConfirmBuyModal.jsx
|
|
│ │ ├── EditItemModal.jsx
|
|
│ │ ├── ImageModal.jsx
|
|
│ │ ├── ImageUploadModal.jsx
|
|
│ │ ├── ItemClassificationModal.jsx
|
|
│ │ ├── SimilarItemModal.jsx
|
|
│ │ └── index.js # Barrel exports
|
|
│ │
|
|
│ ├── forms/ # Form components and input sections
|
|
│ │ ├── AddItemForm.jsx
|
|
│ │ ├── ClassificationSection.jsx
|
|
│ │ ├── ImageUploadSection.jsx
|
|
│ │ └── index.js # Barrel exports
|
|
│ │
|
|
│ ├── items/ # Item display and list components
|
|
│ │ ├── GroceryItem.tsx
|
|
│ │ ├── GroceryListItem.jsx
|
|
│ │ ├── SuggestionList.tsx
|
|
│ │ └── index.js # Barrel exports
|
|
│ │
|
|
│ └── layout/ # Layout and navigation components
|
|
│ ├── AppLayout.jsx
|
|
│ ├── Navbar.jsx
|
|
│ └── index.js # Barrel exports
|
|
│
|
|
├── constants/ # Application constants
|
|
│ ├── classifications.js # Item types, groups, zones
|
|
│ └── roles.js # User roles (viewer, editor, admin)
|
|
│
|
|
├── context/ # React context providers
|
|
│ └── AuthContext.jsx # Authentication context
|
|
│
|
|
├── pages/ # Top-level page components
|
|
│ ├── AdminPanel.jsx # User management dashboard
|
|
│ ├── GroceryList.jsx # Main grocery list page
|
|
│ ├── Login.jsx # Login page
|
|
│ └── Register.jsx # Registration page
|
|
│
|
|
├── styles/ # CSS files (organized by type)
|
|
│ ├── pages/ # Page-specific styles
|
|
│ │ ├── GroceryList.css
|
|
│ │ ├── Login.css
|
|
│ │ └── Register.css
|
|
│ │
|
|
│ ├── components/ # Component-specific styles
|
|
│ │ ├── AddItemWithDetailsModal.css
|
|
│ │ ├── ClassificationSection.css
|
|
│ │ ├── EditItemModal.css
|
|
│ │ ├── ImageUploadSection.css
|
|
│ │ └── Navbar.css
|
|
│ │
|
|
│ ├── theme.css # **GLOBAL THEME VARIABLES** (colors, spacing, typography)
|
|
│ ├── THEME_USAGE_EXAMPLES.css # Examples of using theme variables
|
|
│ ├── App.css # Global app styles
|
|
│ └── index.css # Root styles (uses theme variables)
|
|
│
|
|
├── utils/ # Utility functions
|
|
│ ├── PrivateRoute.jsx # Authentication guard
|
|
│ ├── RoleGuard.jsx # Role-based access guard
|
|
│ └── stringSimilarity.js # String matching utilities
|
|
│
|
|
├── App.jsx # Root app component
|
|
├── main.tsx # Application entry point
|
|
├── config.ts # Configuration (API URL)
|
|
└── types.ts # TypeScript type definitions
|
|
```
|
|
|
|
## Import Patterns
|
|
|
|
### Using Barrel Exports (Recommended)
|
|
|
|
Barrel exports (`index.js` files) allow cleaner imports from component groups:
|
|
|
|
```javascript
|
|
// ✅ Clean barrel import
|
|
import { FloatingActionButton, SortDropdown } from '../components/common';
|
|
import { EditItemModal, SimilarItemModal } from '../components/modals';
|
|
import { AddItemForm, ClassificationSection } from '../components/forms';
|
|
```
|
|
|
|
### Direct Imports (Alternative)
|
|
|
|
You can also import components directly when needed:
|
|
|
|
```javascript
|
|
// Also valid
|
|
import FloatingActionButton from '../components/common/FloatingActionButton';
|
|
import EditItemModal from '../components/modals/EditItemModal';
|
|
```
|
|
|
|
## Component Categories
|
|
|
|
### `common/` - Reusable UI Components
|
|
- **Purpose**: Generic, reusable components used across multiple pages
|
|
- **Examples**: Buttons, dropdowns, form inputs, error messages
|
|
- **Characteristics**: Highly reusable, minimal business logic
|
|
|
|
### `modals/` - Dialog Components
|
|
- **Purpose**: All modal/dialog/popup components
|
|
- **Examples**: Confirmation dialogs, edit forms, image viewers
|
|
- **Characteristics**: Overlay UI, typically used for focused interactions
|
|
|
|
### `forms/` - Form Sections
|
|
- **Purpose**: Form-related components and input sections
|
|
- **Examples**: Multi-step forms, reusable form sections
|
|
- **Characteristics**: Handle user input, validation, form state
|
|
|
|
### `items/` - Item Display Components
|
|
- **Purpose**: Components specific to displaying grocery items
|
|
- **Examples**: Item cards, item lists, suggestion lists
|
|
- **Characteristics**: Domain-specific (grocery items)
|
|
|
|
### `layout/` - Layout Components
|
|
- **Purpose**: Application structure and navigation
|
|
- **Examples**: Navigation bars, page layouts, wrappers
|
|
- **Characteristics**: Define page structure, persistent UI elements
|
|
|
|
## Style Organization
|
|
|
|
### `styles/pages/`
|
|
Page-specific styles that apply to entire page components.
|
|
|
|
### `styles/components/`
|
|
Component-specific styles for individual reusable components.
|
|
|
|
## Benefits of This Structure
|
|
|
|
1. **Scalability**: Easy to add new components without cluttering directories
|
|
2. **Discoverability**: Intuitive naming makes components easy to find
|
|
3. **Maintainability**: Related code is grouped together
|
|
4. **Separation of Concerns**: Clear boundaries between different types of components
|
|
5. **Import Clarity**: Barrel exports reduce import statement complexity
|
|
6. **Team Collaboration**: Clear conventions for where new code should go
|
|
|
|
## Adding New Components
|
|
|
|
When adding a new component, ask:
|
|
|
|
1. **Is it reusable across pages?** → `common/`
|
|
2. **Is it a modal/dialog?** → `modals/`
|
|
3. **Is it form-related?** → `forms/`
|
|
4. **Is it specific to grocery items?** → `items/`
|
|
5. **Does it define page structure?** → `layout/`
|
|
6. **Is it a full page?** → `pages/`
|
|
|
|
Then:
|
|
1. Create the component in the appropriate subdirectory
|
|
2. Add the component to the subdirectory's `index.js` barrel export
|
|
3. Create corresponding CSS file in `styles/pages/` or `styles/components/`
|
|
|
|
## Migration Notes
|
|
|
|
This structure was implemented on January 2, 2026 to organize 20+ components and 10+ CSS files that were previously in flat directories. All import paths have been updated to reflect the new structure.
|
|
|
|
## Theming System
|
|
|
|
The application uses a centralized theming system via CSS custom properties (variables) defined in `styles/theme.css`.
|
|
|
|
### Theme Variables
|
|
|
|
All design tokens are defined in `theme.css` including:
|
|
|
|
- **Colors**: Primary, secondary, semantic (success, danger, warning), neutrals
|
|
- **Spacing**: Consistent spacing scale (xs, sm, md, lg, xl, 2xl, 3xl)
|
|
- **Typography**: Font families, sizes, weights, line heights
|
|
- **Borders**: Widths and radius values
|
|
- **Shadows**: Box shadow presets
|
|
- **Transitions**: Timing functions
|
|
- **Z-index**: Layering system for modals, dropdowns, etc.
|
|
|
|
### Using Theme Variables
|
|
|
|
```css
|
|
/* Instead of hardcoded values */
|
|
.button-old {
|
|
background: #007bff;
|
|
padding: 0.6em 1.2em;
|
|
border-radius: 4px;
|
|
}
|
|
|
|
/* Use theme variables */
|
|
.button-new {
|
|
background: var(--color-primary);
|
|
padding: var(--button-padding-y) var(--button-padding-x);
|
|
border-radius: var(--button-border-radius);
|
|
}
|
|
```
|
|
|
|
### Benefits
|
|
|
|
1. **Consistency**: All components use the same design tokens
|
|
2. **Maintainability**: Change once in `theme.css`, updates everywhere
|
|
3. **Theme Switching**: Easy to implement dark mode (already scaffolded)
|
|
4. **Scalability**: Add new tokens without touching component styles
|
|
5. **Documentation**: Variable names are self-documenting
|
|
|
|
### Utility Classes
|
|
|
|
The theme file includes utility classes for common patterns:
|
|
|
|
```html
|
|
<!-- Spacing -->
|
|
<div class="mt-3 mb-4 p-2">Content</div>
|
|
|
|
<!-- Text styling -->
|
|
<span class="text-primary font-weight-bold">Important</span>
|
|
|
|
<!-- Flexbox -->
|
|
<div class="d-flex justify-between align-center gap-2">Items</div>
|
|
```
|
|
|
|
See `styles/THEME_USAGE_EXAMPLES.css` for complete examples of refactoring existing CSS to use theme variables.
|