npm package: @sahstiva/pace-calculator
Description: A modern, responsive Nuxt 3 application for calculating average running pace across different distance segments with support for custom segments and localStorage persistence
Author: Sahstiva
Latest version: 1.2.0

# 🏃 Pace Calculator

[![Live Demo](https://img.shields.io/badge/demo-pace.sahstiva.com-00DC82?style=flat-square&logo=vercel)](https://pace.sahstiva.com)
[![npm version](https://img.shields.io/npm/v/@sahstiva/pace-calculator.svg?style=flat-square)](https://www.npmjs.com/package/@sahstiva/pace-calculator)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![GitHub stars](https://img.shields.io/github/stars/Sahstiva/pace-calculator?style=flat-square)](https://github.com/Sahstiva/pace-calculator/stargazers)
[![GitHub issues](https://img.shields.io/github/issues/Sahstiva/pace-calculator?style=flat-square)](https://github.com/Sahstiva/pace-calculator/issues)

A modern, responsive Nuxt 3 application for calculating average running pace across different distance segments. Perfect for runners planning their race strategy with variable pacing.

## 🌐 Live Demo

**Try it now: [https://pace.sahstiva.com](https://pace.sahstiva.com)**

## ✨ Features

- **🎯 Distance Presets** — Quick selection of common race distances (5K, 10K, Half Marathon, Marathon)
- **📏 Custom Distance** — Enter any distance manually when no preset is selected
- **🧩 Multiple Segments** — Add unlimited distance segments with individual pace settings
- **⏱️ Time or Pace** — Set either time or pace for each segment; the other is auto-calculated
- **⚡ Auto-Calculate** — Average pace and total time update automatically when any value changes
- **📊 Rest Distance** — Always shows remaining distance with its own time/pace settings
- **💾 Save & Load** — Save your pace calculations to localStorage and load them anytime
- **📤 Export/Import** — Export results to JSON and import them on any device
- **📱 Responsive Design** — Works beautifully on desktop, tablet, and mobile devices
- **🌙 Dark Theme** — Modern dark UI with gradient accents

## 📸 Screenshots

<details>
<summary>Click to view screenshots</summary>

The application features a clean, modern interface with:
- Distance selection with presets
- Dynamic segment management
- Real-time pace calculations
- Saved results management
- Export/Import functionality

</details>

## 🚀 Quick Start

### Prerequisites

- [Node.js](https://nodejs.org/) 18.0.0 or higher
- npm, yarn, or pnpm

### Installation

```bash
# Clone the repository
git clone https://github.com/Sahstiva/pace-calculator.git
cd pace-calculator

# Install dependencies
npm install

# Start development server
npm run dev
```

The application will be available at `http://localhost:3000`

### Build for Production

```bash
# Generate static files (for static hosting)
npm run generate

# Or build for server-side rendering
npm run build

# Preview production build
npm run preview
```

## 📖 How to Use

1. **Select Distance** — Choose a preset distance (5K, 10K, Half Marathon, Marathon) or enter a custom distance
2. **Add Segments** — Click "+ Add Segment" to create distance segments with different paces
3. **Set Segment Details**:
   - Enter the distance for each segment (in km)
   - Enter either **Time** or **Pace** — the other will be calculated automatically
4. **Rest of Distance** — The remaining distance is calculated automatically; set the time or pace for it
5. **View Results** — See your average pace and total time instantly update
6. **Save Results** — Enter a name and save your calculation for later reference
7. **Load Saved** — Click any saved result to restore all settings
8. **Export/Import** — Export your saved results to JSON or import from a file

### Time & Pace Auto-Calculation

Each segment supports both **Time** and **Pace** inputs that are linked:

| You Enter | Auto-Calculated |
|-----------|-----------------|
| Pace (e.g., `5:30`) | Time = Distance × Pace |
| Time (e.g., `10:00`) | Pace = Time ÷ Distance |

When you change the distance, the calculator remembers which field you last edited and recalculates the other.

### Input Formats

**Pace formats:**
- `5:30` — Standard format (5 minutes 30 seconds per km)
- `5.30` — Dot separator
- `530` — Without separator
- `5` — Minutes only (assumes 0 seconds)

**Time formats:**
- `5:30` — mm:ss (5 minutes 30 seconds)
- `1:30:00` — hh:mm:ss (1 hour 30 minutes)
- `330` — Plain seconds

## 🛠️ Tech Stack

| Technology | Purpose |
|------------|---------|
| [Nuxt 3](https://nuxt.com/) | Vue.js meta-framework |
| [Vue 3](https://vuejs.org/) | Composition API with TypeScript |
| [TypeScript](https://www.typescriptlang.org/) | Type safety |
| CSS Variables | Custom theming system |
| localStorage | Data persistence |

## 🌍 Deployment

The application is deployed on **AWS Amplify** with **Cloudflare** for DNS, SSL, and protection.

- **Production URL**: [https://pace.sahstiva.com](https://pace.sahstiva.com)
- **Hosting**: AWS Amplify
- **CDN/Security**: Cloudflare

## 📁 Project Structure

```
pace-calculator/
├── assets/
│   └── css/
│       └── main.css          # Global styles with CSS variables
├── pages/
│   └── index.vue             # Main calculator page
├── app.vue                   # App wrapper
├── nuxt.config.ts            # Nuxt configuration
├── package.json              # Dependencies and scripts
└── tsconfig.json             # TypeScript configuration
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.

## 📝 Changelog

See [CHANGELOG.md](CHANGELOG.md) for a list of changes and version history.

## 🐛 Bug Reports

If you discover a bug, please [create an issue](https://github.com/Sahstiva/pace-calculator/issues/new) with:
- A clear description of the bug
- Steps to reproduce
- Expected vs actual behavior
- Screenshots if applicable

## 💡 Feature Requests

Have an idea for a new feature? [Open an issue](https://github.com/Sahstiva/pace-calculator/issues/new) and describe:
- What you'd like to see
- Why it would be useful
- Any implementation ideas

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Inspired by the needs of runners planning their race pacing strategies
- Built with [Nuxt 3](https://nuxt.com/) and [Vue 3](https://vuejs.org/)
- Hosted on [AWS Amplify](https://aws.amazon.com/amplify/) with [Cloudflare](https://cloudflare.com/) protection
- Icons and emojis for visual enhancement

## 📬 Contact

- **Website**: [https://pace.sahstiva.com](https://pace.sahstiva.com)
- **GitHub**: [@Sahstiva](https://github.com/Sahstiva)
- **Repository**: [https://github.com/Sahstiva/pace-calculator](https://github.com/Sahstiva/pace-calculator)

---

<p align="center">
  Made with ❤️ for runners everywhere
</p>

<p align="center">
  <a href="https://pace.sahstiva.com">pace.sahstiva.com</a>
</p>