Initial commit: Coastal Timesheet App with comprehensive features

- Employee name validation for all submissions - Complete entry validation (all fields required when any field has input) - Dynamic auto-resizing work description fields - Optimized field layout (Homeowner → Hours → Work Description) - Professional PDF generation with validation - Email/share functionality with validation - Data import/export capabilities - Dark/light theme support - Mobile-responsive design - Local data persistence - Multiple entries per day support - Custom homeowner management - Comprehensive README with deployment instructions - Production build ready for web hosting
2025-08-19 08:21:20 -04:00
commit b5e7c8796f
35 changed files with 9207 additions and 0 deletions
@@ -0,0 +1,189 @@
+# 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.*