coastal_timesheet/README.md

# Coastal Contracting Timesheet App

A modern, responsive timesheet application built with React for tracking work hours and generating professional PDF timesheets. Features comprehensive validation, dynamic field layouts, and seamless data management.

![Coastal Timesheet App Screenshot](./screenshot.png)
*Screenshot showing the timesheet interface with validation, dynamic fields, and professional layout*

## ✨ Features

### 📊 **Time Tracking & Management**
- **Weekly Time Tracking**: Track work hours for each day of the week with multiple entries per day
- **Dynamic Date Navigation**: Navigate between weeks with intuitive date picker controls
- **Flexible Entry Management**: Add, remove, and modify time entries as needed
- **Auto-saving**: Automatically saves all data to browser localStorage

### 🏠 **Homeowner Management**
- **Pre-loaded Homeowners**: Comprehensive list of default homeowner names and addresses
- **Custom Homeowners**: Add and save custom homeowner names that persist across sessions
- **Smart Dropdown**: Searchable dropdown with autocomplete functionality

### ✅ **Smart Validation System**
- **Required Employee Name**: Employee name must be entered before exporting timesheets
- **Complete Entry Validation**: When any field is filled, all three fields (homeowner, hours, work description) become required
- **Visual Feedback**: Red borders, asterisks, and warning messages guide users to complete entries
- **Export Protection**: PDF generation disabled until all validation requirements are met

### 📝 **Enhanced User Interface**
- **Dynamic Work Description Fields**: Auto-resizing text areas that expand to show all content without scrolling
- **Optimized Field Layout**: Homeowner → Hours → Work Description order with maximum space for descriptions
- **Today Highlighting**: Current day is visually highlighted for easy identification
- **Dark/Light Mode**: Toggle between themes with persistent user preference

### 📄 **Professional PDF Export**
- **Download PDF**: Generate and download professional timesheet PDFs
- **Email Integration**: Share PDFs via device share sheet or download with pre-filled email subject
- **Optimized Layout**: PDF layout matches UI with proper field sizing and professional formatting
- **Validation Integration**: Only complete, valid timesheets can be exported

### 💾 **Data Management**
- **Import/Export**: Backup and restore timesheet data with JSON export/import
- **Week-based Storage**: Each week's data stored separately for better organization
- **Custom Homeowner Persistence**: Added homeowners saved across all sessions
- **Cross-device Compatibility**: Works on desktop, tablet, and mobile devices

### 📱 **Responsive Design**
- **Mobile-first**: Optimized for touch interfaces and small screens
- **Adaptive Layouts**: Fields reorganize appropriately for different screen sizes
- **Touch-friendly**: Large buttons and touch targets for mobile users

## 🚀 Getting Started

### Prerequisites

- Node.js (version 16 or higher)
- npm or yarn

### Installation

1. Clone or download the project files
2. Install dependencies:
   ```bash
   npm install
   ```

3. Start the development server:
   ```bash
   npm run dev
   ```

4. Open [http://localhost:5173](http://localhost:5173) in your browser

### Building for Production

```bash
npm run build
```

The built files will be in the `dist/` directory, ready for web hosting.

### Preview Production Build

```bash
npm run preview
```

## 📖 Usage Guide

### 1. **Setup**
- Enter your **Employee Name** (required for all exports)
- Select the week you want to track using the date picker

### 2. **Adding Time Entries**
- Click "Add Entry" for any day to create multiple entries
- Fill in all three fields for each entry:
  - **Homeowner**: Select from dropdown or add custom names
  - **Hours Worked**: Enter decimal hours (e.g., 2.5 for 2 hours 30 minutes)  
  - **Work Description**: Detailed description of work performed (auto-expanding field)

### 3. **Validation & Completion**
- **Red asterisks (*)** indicate required fields
- **Warning messages** appear for incomplete entries
- **Export buttons** are disabled until all requirements are met

### 4. **Export Options**
- **Download PDF**: Save a printable PDF to your device
- **Share/Email PDF**: Use device share functionality or download with email setup
- **Import/Export Data**: Backup/restore your timesheet data

### 5. **Additional Features**
- **Theme Toggle**: Switch between light and dark modes
- **Office Contact**: Download contact card for easy email setup

## 🗂️ Data Storage

- **Local Browser Storage**: All data stored locally, no external servers
- **Weekly Organization**: Each week stored as separate dataset
- **Persistent Settings**: Theme preferences and custom homeowners preserved
- **Privacy-focused**: Your data never leaves your device

## 🛠️ Tech Stack

- **Frontend Framework**: React 18 with Vite
- **Styling**: Tailwind CSS with responsive design
- **PDF Generation**: @react-pdf/renderer for professional documents
- **Icons**: Lucide React icon library
- **Storage**: Browser localStorage API
- **Build Tool**: Vite for fast development and optimized builds

## 📁 Project Structure

```
src/
├── components/              # React components
│   ├── TimeSheet.jsx       # Main timesheet interface
│   ├── DayEntries.jsx      # Day-specific entry management
│   ├── TimeEntryRow.jsx    # Individual entry row (legacy)
│   ├── DatePicker.jsx      # Week navigation
│   ├── HomeownerDropdown.jsx # Homeowner selection
│   ├── ThemeToggle.jsx     # Dark/light mode toggle
│   ├── PDFExport.jsx       # PDF download functionality
│   ├── EmailPDF.jsx        # PDF sharing functionality
│   ├── TimesheetPDF.jsx    # PDF document structure
│   ├── ImportExport.jsx    # Data backup/restore
│   └── MiniCalendar.jsx    # Calendar widget
├── hooks/                   # Custom React hooks
│   ├── useTimeSheet.js     # Timesheet state & validation
│   └── useTheme.js         # Theme management
├── utils/                   # Utility functions
│   └── dateUtils.js        # Date manipulation helpers
├── App.jsx                  # Main application component
├── main.jsx                 # Application entry point
└── index.css               # Global styles
```

## 🔧 Configuration Files

- `vite.config.js` - Vite build configuration
- `tailwind.config.js` - Tailwind CSS customization
- `postcss.config.js` - PostCSS processing
- `package.json` - Dependencies and scripts

## 🌐 Deployment

The built application is a static site that can be deployed to any web hosting service:

1. Run `npm run build`
2. Upload the contents of the `dist/` directory to your web server
3. Ensure your server serves `index.html` for all routes (SPA configuration)

Compatible with: Netlify, Vercel, GitHub Pages, traditional web hosting, and more.

## 📋 Features Summary

✅ **Employee name validation**  
✅ **Complete entry validation (all fields required when any field has input)**  
✅ **Dynamic auto-resizing work description fields**  
✅ **Optimized field order (Homeowner → Hours → Work Description)**  
✅ **Professional PDF generation with validation**  
✅ **Email/share functionality**  
✅ **Data import/export**  
✅ **Dark/light theme support**  
✅ **Mobile-responsive design**  
✅ **Local data persistence**  
✅ **Multiple entries per day**  
✅ **Custom homeowner management**

---

*Built for Coastal Contracting of FL - Making timesheet management simple and professional.*