vue-weather-ui/README.md

A beautiful Vue 3 weather UI components library with mini mode support and QWeather integration

# Vue Weather UI

A beautiful weather components library for Vue 3, integrated with QWeather API and icons.

## Features

- 🌡️ Weather Card - Current weather display with detailed information
- 🕐 24 Hour Forecast - Hourly weather prediction with scrollable interface
- 📅 7 Day Forecast - Weekly weather prediction with temperature trends
- 📊 Historical Timeline - Interactive historical weather timeline with auto-play and month filtering
- 🎨 Flat Design Icons - Clean, modern SVG icons with responsive scaling
- 🎮 Interactive Controls - Play/pause and reset buttons with smooth animations
- 🌙 Dark Theme - Light and dark theme support with proper icon visibility
- 🌍 QWeather Integration - Professional weather icons and data
- 📱 Responsive - Mobile-friendly design with mini mode support
- 🎯 TypeScript - Full TypeScript support
- 📦 Easy to Use - Simple installation and API

## Installation

```bash
npm install vue-weather-ui
```

## Usage

### Global Installation

```typescript
import { createApp } from 'vue'
import VueWeatherUI from 'vue-weather-ui'
import 'vue-weather-ui/dist/style.css'

const app = createApp(App)
app.use(VueWeatherUI)
app.mount('#app')
```

### Local Component Import

```vue
<template>
  <WeatherCard :data="weatherData" />
  <HourlyForecast :data="weatherData" />
  <DailyForecast :data="weatherData" />
  <HistoricalTimeline :data="weatherData" @day-select="onDaySelect" />
</template>

<script setup>
import { WeatherCard, HourlyForecast, DailyForecast, HistoricalTimeline } from 'vue-weather-ui'
import 'vue-weather-ui/dist/style.css'

const weatherData = ref(/* your weather data */)
</script>
```

## Components

### WeatherCard

Display current weather information with location details and update time.

```vue
<WeatherCard 
  :data="weatherData" 
  :show-details="true"
  :show-title="true"
  :mini="false"
  theme="light"
  locale="zh"
/>
```

**Props:**
- `data`: WeatherData - Weather data object
- `showDetails`: boolean - Show detailed weather information
- `showTitle`: boolean - Show/hide component title and location info
- `mini`: boolean - Enable compact mode with simplified layout
- `theme`: 'light' | 'dark' - Theme mode
- `locale`: 'zh' | 'en' - Language locale

**Features:**
- Current temperature with large display
- Weather icon and description
- Location information (name, region, country)
- Detailed weather data (feels like, humidity, wind, pressure, visibility, precipitation)
- Update time display
- Mini mode with compact layout
- Responsive design

### HourlyForecast

24-hour weather forecast with horizontal scrolling and current hour highlighting.

```vue
<HourlyForecast 
  :data="weatherData" 
  :hours="24"
  :show-title="true"
  :mini="false"
  theme="light"
  locale="zh"
/>
```

**Props:**
- `data`: WeatherData - Weather data object
- `hours`: number - Number of hours to display (default: 24)
- `showTitle`: boolean - Show/hide component title
- `mini`: boolean - Enable compact mode with simplified layout
- `theme`: 'light' | 'dark' - Theme mode
- `locale`: 'zh' | 'en' - Language locale

**Features:**
- Horizontal scrollable interface
- Current hour highlighting with "Now" label
- Hourly temperature, weather icon, and description
- Humidity and wind speed details
- Responsive design with mini mode support
- Smooth scrolling experience

### DailyForecast

7-day weather forecast with temperature trends, sunrise/sunset times, and weather details.

```vue
<DailyForecast 
  :data="weatherData" 
  :days="7"
  :show-title="true"
  :mini="false"
  theme="light"
  locale="zh"
/>
```

**Props:**
- `data`: WeatherData - Weather data object
- `days`: number - Number of days to display (default: 7)
- `showTitle`: boolean - Show/hide component title
- `mini`: boolean - Enable compact mode with simplified layout
- `theme`: 'light' | 'dark' - Theme mode
- `locale`: 'zh' | 'en' - Language locale

**Features:**
- Daily temperature ranges with visual temperature bar
- Day and night weather icons with descriptions
- Today/Tomorrow automatic labeling
- Sunrise and sunset times
- Wind direction and humidity information
- Precipitation and UV index details
- Responsive grid layout with mobile support
- Mini mode with simplified display

### HistoricalTimeline

Interactive historical weather timeline with month filtering, auto-play controls, and flat design icons.

```vue
<HistoricalTimeline 
  :data="weatherData" 
  :auto-play="false"
  :auto-play-interval="2000"
  :show-controls="true"
  :show-title="true"
  theme="light"
  locale="zh"
  @day-select="onDaySelect"
  @day-change="onDayChange"
/>
```

**Props:**
- `data`: WeatherData - Weather data object
- `autoPlay`: boolean - Enable auto-play
- `autoPlayInterval`: number - Auto-play interval in milliseconds
- `style`: TimelineStyle - Custom timeline styles
- `showControls`: boolean - Show/hide control buttons (play/pause, reset)
- `showTitle`: boolean - Show/hide component title
- `mini`: boolean - Enable compact mode
- `theme`: 'light' | 'dark' - Theme mode
- `locale`: 'zh' | 'en' - Language locale

**Events:**
- `day-select`: Emitted when a day is selected
- `day-change`: Emitted when the displayed day changes

**Features:**
- Month filtering dropdown
- Play/pause auto-play functionality with flat SVG icons
- Reset button to clear selection and stop auto-play
- Interactive day selection with visual feedback
- Current day highlighting
- Smooth scrolling to selected days
- Responsive design with mini mode support

## Data Structure

### WeatherData

```typescript
interface WeatherData {
  location: Location
  now: WeatherNow
  hourly: WeatherHourly[]
  daily: WeatherDaily[]
  historical: HistoricalWeather[]
}
```

### Location

```typescript
interface Location {
  name: string
  country: string
  adm1: string
  adm2: string
  lat: string
  lon: string
  tz: string
}
```

### WeatherNow

```typescript
interface WeatherNow {
  fxTime: string
  temp: string
  icon: string
  text: string
  wind360: string
  windDir: string
  windScale: string
  windSpeed: string
  humidity: string
  precip: string
  pressure: string
  vis: string
  cloud: string
  dew: string
}
```

## Development

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Build library
npm run build:lib

# Build demo
npm run build

# Type check
npm run typecheck
```

## QWeather Integration

This library uses QWeather icons and follows their API data structure. You can get your own API key from [QWeather](https://www.qweather.com/).

## License

MIT

## Contributing

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