https://github.com/yousifabozid/phonebook
https://github.com/yousifabozid/phonebook
Last synced: 25 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/yousifabozid/phonebook
- Owner: YousifAbozid
- Created: 2025-03-25T08:11:30.000Z (about 1 month ago)
- Default Branch: source
- Last Pushed: 2025-03-25T12:41:57.000Z (about 1 month ago)
- Last Synced: 2025-03-25T13:21:58.310Z (about 1 month ago)
- Language: TypeScript
- Homepage: https://yousifabozid.github.io/phonebook/
- Size: 1.07 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Phonebook App
A modern web application for managing and searching contacts from CSV and VCF files. Easily import, organize, find, and export your contacts with a beautiful and responsive user interface.
## Features
- 📱 Import contacts from CSV and VCF files with drag-and-drop support
- 🔍 Advanced search functionality across all contact fields
- 📊 Organized contact display with alphabetical grouping
- 📤 Export contacts to CSV and VCF formats
- 🌓 Dark mode support with system preference detection
- 🖼️ Support for contact photos and avatars
- 📞 Direct call, message, and email actions for contacts
- 📱 Fully responsive design for all devices
## Technologies Used
This application is built with modern web technologies for optimal performance and user experience:
- **React 19**: Latest version of the popular UI library with improved performance
- **TypeScript**: Static type checking for more robust code
- **Vite**: Next generation frontend tooling for fast development and optimized builds
- **Tailwind CSS v4**: Utility-first CSS framework with built-in dark mode support
- **Framer Motion**: Production-ready animation library for React
- **ESLint**: Linting utility for identifying and fixing code problems
- **Prettier**: Code formatter for consistent styling
- **Husky**: Git hooks to enforce code quality checks before commits
- **GitHub Actions**: CI/CD pipeline for automated deployment
## Getting Started
### Installation
1. Clone this repository:
```bash
git clone https://github.com/YousifAbozid/phonebook.git
cd phonebook
```
2. Install dependencies:
```bash
npm install
```
3. Start the development server:
```bash
npm run dev
```
4. Open your browser and visit http://localhost:3000
### Project Structure
```
phonebook/
├── .github/ # GitHub Actions workflows
├── .husky/ # Git hooks configuration
├── src/
│ ├── components/ # UI components
│ │ ├── ContactList.tsx # Contact list display component
│ │ ├── FileUpload.tsx # File upload component
│ │ ├── SearchBar.tsx # Search functionality
│ │ ├── ThemeToggle.tsx # Dark/light mode toggle
│ │ └── ... # Other components
│ ├── types/ # TypeScript type definitions
│ │ └── Contact.ts # Contact interface
│ ├── utils/ # Utility functions
│ │ ├── csvParser.ts # CSV file parsing
│ │ ├── vcfParser.ts # VCF file parsing
│ │ └── exportContacts.ts # Contact export functions
│ ├── App.tsx # Main application component
│ ├── main.tsx # Application entry point
│ └── globals.css # Global styles and theme variables
├── index.html # HTML template
├── vite.config.ts # Vite configuration
├── tsconfig.json # TypeScript configuration
├── eslint.config.js # ESLint configuration
└── package.json # Project dependencies and scripts
```
## Available Scripts
The application includes the following npm scripts:
- **`npm run dev`**: Start the development server
- **`npm run build`**: Type-check and build the app for production
- **`npm run preview`**: Preview the production build locally
- **`npm run lint`**: Run ESLint to check for code issues
- **`npm run lint:fix`**: Run ESLint and automatically fix issues
- **`npm run format`**: Run Prettier to format all files
- **`npm run format:check`**: Check if files are properly formatted
- **`npm run fix-all`**: Run both lint:fix and format to fix all issues
- **`npm run type-check`**: Run TypeScript type checking
- **`npm run upgrade`**: Update all dependencies to their latest versions
## Theme System
This application includes a carefully crafted theming system with semantic color variables for both light and dark modes.
### Color System Structure
Colors are organized in the following categories:
- **Light/Dark Background Colors**: Primary, secondary, tertiary, and hover states
- **Light/Dark Text Colors**: Primary, secondary, tertiary, and inverted text
- **Accent Colors**: Primary, secondary, success, warning, danger
- **Border Colors**: Light and dark mode borders
- **Shadow Colors**: For consistent box-shadow effects
### How to Use Theme Colors
You can apply theme colors directly using Tailwind utility classes:
```jsx
// Background colors
...
// Text colors
...
// Border colors
...
// Accent colors
Primary Action
Success message
```
## Contact Data Handling
### Importing Contacts
The application supports importing contacts from CSV and VCF (vCard) files:
1. **CSV Import**: Supports standard CSV files with headers for name, phone number, email, address, company, and notes
2. **VCF Import**: Parses vCard files (versions 2.1, 3.0, and 4.0) with support for multiple contacts in a single file
### Contact Data Structure
Contacts are represented with the following structure:
```typescript
interface Contact {
id: string;
name: string;
phoneNumber: string;
email?: string;
address?: string;
company?: string;
notes?: string;
photo?: string; // Base64 encoded image or URL
}
```
### Exporting Contacts
Contacts can be exported to:
1. **CSV Format**: Standard CSV file with all contact fields
2. **VCF Format**: Industry-standard vCard format compatible with most contact applications
## Dark Mode Implementation
This application includes a ready-to-use dark mode implementation:
1. **Theme Toggle Component**: Provides a button to switch between light and dark modes
2. **Local Storage**: User preference is saved to local storage so it persists between visits
3. **System Preference Detection**: Automatically detects the user's system preference for dark/light mode on first visit
## Development Tools
### ESLint Configuration
This project uses ESLint to enforce code quality with:
- React recommended rules
- TypeScript integration
- Import order rules
- React Hooks rules
### Prettier Configuration
Prettier ensures consistent code formatting with the following rules:
```json
{
"singleQuote": true,
"semi": true,
"tabWidth": 2,
"printWidth": 80,
"trailingComma": "es5",
"arrowParens": "avoid",
"endOfLine": "lf"
}
```
### Continuous Integration
The project includes GitHub Actions workflows for:
- Lint and type checking on pull requests
- Automated building and deployment to GitHub Pages
## License
MIT