|
1 | | -<div align="center"> |
2 | | -<img width="1200" height="475" alt="GHBanner" src="https://github.com/user-attachments/assets/0aa67016-6eaf-458a-adb2-6e31a0763ed6" /> |
3 | | -</div> |
| 1 | +# Epoch |
4 | 2 |
|
5 | | -# Run and deploy your AI Studio app |
| 3 | +**See your life unfold.** A beautiful, intuitive timeline editor that helps you visualize your journey—past milestones, present projects, and future dreams—all in one panoramic view. |
6 | 4 |
|
7 | | -This contains everything you need to run your app locally. |
| 5 | +## Features |
8 | 6 |
|
9 | | -View your app in AI Studio: https://ai.studio/apps/drive/1BIBEpiSaPPg97k-ECttw5iztWrXJqPYd |
| 7 | +- **Multi-Track Timeline** - Organize events into separate tracks (Work, Personal, Learning, etc.) |
| 8 | +- **Drag & Drop** - Move events by dragging, resize by dragging edges |
| 9 | +- **Smart Lane Stacking** - Overlapping events automatically stack in lanes |
| 10 | +- **Dynamic Track Heights** - Tracks expand to fit overlapping events |
| 11 | +- **Zoom Controls** - From year overview to day-level detail |
| 12 | +- **Color Coding** - Customizable colors for tracks and individual events |
| 13 | +- **Import/Export** - Save and load timelines as JSON files |
| 14 | +- **Responsive Design** - Works on desktop and tablet |
10 | 15 |
|
11 | | -## Run Locally |
| 16 | +## Quick Start |
12 | 17 |
|
13 | | -**Prerequisites:** Node.js |
| 18 | +**Prerequisites:** Node.js 18+ |
14 | 19 |
|
| 20 | +```bash |
| 21 | +# Install dependencies |
| 22 | +npm install |
| 23 | +# or |
| 24 | +pnpm install |
15 | 25 |
|
16 | | -1. Install dependencies: |
17 | | - `npm install` |
18 | | -2. Set the `GEMINI_API_KEY` in [.env.local](.env.local) to your Gemini API key |
19 | | -3. Run the app: |
20 | | - `npm run dev` |
| 26 | +# Start development server |
| 27 | +npm run dev |
| 28 | +# or |
| 29 | +pnpm run dev |
| 30 | +``` |
| 31 | + |
| 32 | +## Usage |
| 33 | + |
| 34 | +| Action | How | |
| 35 | +| ---------------- | ------------------------------------------- | |
| 36 | +| **Add Event** | Double-click on empty canvas | |
| 37 | +| **Edit Event** | Double-click on an event | |
| 38 | +| **Move Event** | Drag the event | |
| 39 | +| **Resize Event** | Drag the left or right edge | |
| 40 | +| **Add Track** | Click the + button in the sidebar | |
| 41 | +| **Edit Track** | Hover over track name, click "Edit" | |
| 42 | +| **Zoom** | Use zoom controls in header or scroll wheel | |
| 43 | +| **Pan** | Click and drag on empty canvas | |
| 44 | + |
| 45 | +## 🏗️ Tech Stack |
| 46 | + |
| 47 | +- **React 19** - UI framework |
| 48 | +- **TypeScript** - Type safety |
| 49 | +- **Vite** - Build tool and dev server |
| 50 | +- **Tailwind CSS** - Styling |
| 51 | +- **Lucide React** - Icons |
| 52 | + |
| 53 | +## 📁 Project Structure |
| 54 | + |
| 55 | +``` |
| 56 | +├── App.tsx # Main application component |
| 57 | +├── components/ |
| 58 | +│ ├── AppHeader.tsx # Header with zoom controls |
| 59 | +│ ├── TimelineCanvas.tsx # Main timeline rendering |
| 60 | +│ ├── TrackSidebar.tsx # Track list sidebar |
| 61 | +│ ├── EventModal.tsx # Event editor modal |
| 62 | +│ ├── TrackModal.tsx # Track editor modal |
| 63 | +│ └── DataModal.tsx # Import/export settings |
| 64 | +├── utils/ |
| 65 | +│ ├── dateUtils.ts # Date manipulation helpers |
| 66 | +│ └── eventLanes.ts # Lane calculation for overlapping events |
| 67 | +├── types.ts # TypeScript interfaces |
| 68 | +└── constants.ts # Default data and configuration |
| 69 | +``` |
| 70 | + |
| 71 | +## 🎨 Customization |
| 72 | + |
| 73 | +### Colors |
| 74 | + |
| 75 | +Edit the `COLOR_PALETTE` in `constants.ts` to customize available colors: |
| 76 | + |
| 77 | +```typescript |
| 78 | +export const COLOR_PALETTE = [ |
| 79 | + "#ef4444", // Red |
| 80 | + "#f97316", // Orange |
| 81 | + "#10b981", // Emerald |
| 82 | + "#3b82f6", // Blue |
| 83 | + // ... add more |
| 84 | +]; |
| 85 | +``` |
| 86 | + |
| 87 | +### Zoom Levels |
| 88 | + |
| 89 | +Adjust zoom levels in `constants.ts`: |
| 90 | + |
| 91 | +```typescript |
| 92 | +export const ZOOM_LEVELS = [0.5, 1, 2.5, 5, 10, 25, 50, 100, 200]; |
| 93 | +// Values represent pixels per day |
| 94 | +``` |
| 95 | + |
| 96 | +## Data Format |
| 97 | + |
| 98 | +Epoch uses a simple JSON format for import/export: |
| 99 | + |
| 100 | +```json |
| 101 | +{ |
| 102 | + "tracks": [{ "id": "1", "title": "Work", "color": "#3b82f6", "order": 0 }], |
| 103 | + "events": [ |
| 104 | + { |
| 105 | + "id": "e1", |
| 106 | + "trackId": "1", |
| 107 | + "title": "Project Launch", |
| 108 | + "startDate": "2024-01-15", |
| 109 | + "endDate": "2024-02-28", |
| 110 | + "color": "#3b82f6" |
| 111 | + } |
| 112 | + ] |
| 113 | +} |
| 114 | +``` |
| 115 | + |
| 116 | +## Deployment |
| 117 | + |
| 118 | +### GitHub Pages (Automatic) |
| 119 | + |
| 120 | +This project includes a GitHub Actions workflow for automatic deployment: |
| 121 | + |
| 122 | +1. Push your code to the `main` branch |
| 123 | +2. Go to **Settings → Pages** in your GitHub repository |
| 124 | +3. Set **Source** to "GitHub Actions" |
| 125 | +4. The site will deploy automatically on every push |
| 126 | + |
| 127 | +### Manual Build |
| 128 | + |
| 129 | +```bash |
| 130 | +# Build for production |
| 131 | +npm run build |
| 132 | +# or |
| 133 | +pnpm build |
| 134 | + |
| 135 | +# Preview the build locally |
| 136 | +npm run preview |
| 137 | +``` |
| 138 | + |
| 139 | +The built files will be in the `dist/` folder, ready to deploy to any static hosting service. |
| 140 | + |
| 141 | +## Contributing |
| 142 | + |
| 143 | +Contributions are welcome! Please feel free to submit a Pull Request. |
| 144 | + |
| 145 | +1. Fork the repository |
| 146 | +2. Create your feature branch (`git checkout -b feature/amazing-feature`) |
| 147 | +3. Commit your changes (`git commit -m 'Add amazing feature'`) |
| 148 | +4. Push to the branch (`git push origin feature/amazing-feature`) |
| 149 | +5. Open a Pull Request |
0 commit comments