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.

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:

   npm install
   

3. Start the development server:

   npm run dev
   

4. Open http://localhost:5173 in your browser

Building for Production

npm run build

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

Preview Production Build

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.