# Vue/Laravel Development Guidelines

## Core Principles
- Maintain absolute consistency across all pages and components
- Build for reusability first
- Seek clarity before implementation
- Make no assumptions

## Technical Stack Requirements
- TypeScript, Node.js, Vite, Vue.js, Vue Router, Pinia
- VueUse, Headless UI, Element Plus, Tailwind
- Laravel backend integration

## Code Style and Structure
- Write concise, maintainable, and technically accurate TypeScript code
- Use functional and declarative programming patterns; avoid classes
- Favor iteration and modularization to adhere to DRY principles
- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError)
- Organize files systematically: each file should contain only related content

## Naming Conventions
- Use lowercase with dashes for directories (e.g., components/auth-wizard)
- Favor named exports for functions
- Consistent naming patterns across similar components

## TypeScript Usage
- Use TypeScript for all code
- Prefer interfaces over types for their extendability and ability to merge
- Avoid enums; use maps instead for better type safety and flexibility
- Use functional components with TypeScript interfaces

## Syntax and Formatting
- Use the "function" keyword for pure functions
- Always use the Vue Composition API script setup style
- Consistent code formatting across all files

## UI Consistency Standards

### Component Reusability
- Create shared components whenever two or more components have similar structure
- Place reusable components in `/components/shared` directory
- Document each shared component's props, events, and usage examples
- Implement atomic design principles: atoms → molecules → organisms

### Visual Consistency
- Maintain consistent styling for similar UI elements across all pages
- Use unified color scheme defined in Tailwind config
- Standardize component variants (primary, secondary, danger, etc.)
- Ensure consistent spacing, padding, and margins

### Standardized UI Elements

#### Buttons
- Use consistent button components across all actions
- Maintain uniform styling for similar actions
- Standard variants: primary, secondary, danger, ghost
- Consistent padding, font size, and border radius

#### Forms
- Use consistent form layouts and spacing
- Standardize input styling, validation messages, and error states
- Uniform label positioning and styling
- Consistent helper text and error message placement

## Implementation Standards

### Data Tables
- Follow the established pattern in `resources/js/src/views/income/customers/index.vue` and `resources/js/src/views/expense/vendors/index.vue`
- Maintain consistent implementation across all listing pages
- Use standard table structure with uniform:
  - Header styling
  - Pagination controls
  - Sorting mechanisms
  - Filtering interfaces
  - Empty states
  - Loading indicators

### Modal Management
- Base all modals on the patterns established in:
  - `resources/js/src/components/modals/income/CreateCustomerModal.vue`
  - `resources/js/src/components/modals/expense/CreateVendorModal.vue`
- Maintain consistent modal structure and behavior
- Follow established patterns for:
  - Modal triggers
  - Content layout
  - Action buttons
  - Error handling
  - Loading states

### Form Components
- Use `resources/js/src/components/forms/ResourceSelector.vue` as the standard for form resource selection
- Implement consistent form patterns across all CRUD operations
- For dropdowns, utilize `resources/js/src/components/forms/CustomDropdown.vue`
- Maintain uniform:
  - Input styling
  - Validation patterns
  - Error messages
  - Helper text
  - Loading states

### API Integration
- Utilize the `$api` object (`resources/js/src/utils/api.ts`) for all API calls
- Implement consistent:
  - Error handling
  - Retry logic
  - Response processing
  - Request parameter formatting
  - Loading state management

### Store Management
- Follow the pattern established in `resources/js/src/stores/vendors.ts`
- Maintain consistent store structure across all modules
- Implement uniform:
  - State management
  - Actions/mutations
  - Error handling
  - Loading states

### Navigation and Routing
- Implement breadcrumbs following `resources/js/src/components/Breadcrumb.vue`
  - Reference implementations: customer and vendor views
  - Maintain consistent structure and styling
- Follow router implementation in `resources/js/src/router/index.ts`
- Ensure consistent:
  - Route naming
  - Navigation guards
  - Route meta handling
  - Error states

### Import/Export Functionality
- Base implementation on `resources/js/src/components/ImportExport.vue`
- Maintain consistent:
  - File handling
  - Error reporting
  - Progress indicators
  - Success/failure states

## UI and Styling
- Use Tailwind for components and styling
- Implement responsive design with Tailwind CSS; use desktop-first approach
- Maintain consistent responsive breakpoints

## Performance Optimization
- Leverage VueUse functions for enhanced reactivity and performance
- Wrap asynchronous components in Suspense with fallback UI
- Use dynamic loading for non-critical components
- Optimize images: use WebP format, include size data, implement lazy loading
- Implement optimized chunking strategy during Vite build process
- Optimize Web Vitals (LCP, CLS, FID) using Lighthouse or WebPageTest

## File Structure
- Maintain organized directory structure:
```
resources/js/src/
├── components/
│   ├── shared/
│   ├── forms/
│   ├── modals/
│   └── [feature]/
├── views/
│   ├── income/
│   ├── expense/
│   └── [domain]/
├── stores/
├── router/
└── utils/
```

## Component Introduction Protocol
1. Before creating new UI components:
   - Check if similar component exists
   - Document the need for new component
   - Seek approval for new component creation
   - Share proposed design and implementation approach

## State Management
- Consistent approach to loading states
- Uniform error handling
- Standard success/failure notifications
- Consistent data fetching patterns

## Communication Protocol
- Seek clarification before making assumptions
- Document decisions and reasoning
- Request approval for:
  - New UI components
  - Pattern deviations
  - Architecture changes
  - Third-party library additions

## Best Practices

### Component Creation
- Before creating new components:
  1. Review existing implementations in corresponding directories
  2. Follow established patterns from similar components
  3. Seek approval for any pattern deviations
  4. Document implementation decisions

### Code Consistency
- Reference existing implementations when creating new features
- Maintain parallel structure between similar features
- Follow established patterns for:
  - Component organization
  - State management
  - Error handling
  - User interaction
  - Loading states

### Documentation and Maintenance
- Create and maintain a component library
- Document all shared components
- Regular UI consistency audits
- Maintain a living style guide
- Code review checklist must include UI consistency verification
