diff --git a/custom_components/tibber_prices/images/charts/rolling-window-autoszoom.jpeg b/custom_components/tibber_prices/images/charts/rolling-window-autoszoom.jpeg
new file mode 100644
index 0000000..6cb2345
Binary files /dev/null and b/custom_components/tibber_prices/images/charts/rolling-window-autoszoom.jpeg differ
diff --git a/custom_components/tibber_prices/images/charts/rolling-window.jpg b/custom_components/tibber_prices/images/charts/rolling-window.jpg
new file mode 100644
index 0000000..a113a34
Binary files /dev/null and b/custom_components/tibber_prices/images/charts/rolling-window.jpg differ
diff --git a/custom_components/tibber_prices/images/charts/today.jpeg b/custom_components/tibber_prices/images/charts/today.jpeg
new file mode 100644
index 0000000..8674bb4
Binary files /dev/null and b/custom_components/tibber_prices/images/charts/today.jpeg differ
diff --git a/docs/user/README.md b/docs/user/README.md
index 934cc4a..1ad3dbb 100644
--- a/docs/user/README.md
+++ b/docs/user/README.md
@@ -11,6 +11,7 @@ Welcome to Tibber Prices! This integration provides enhanced electricity price d
- **[Dynamic Icons](dynamic-icons.md)** - State-based automatic icon changes
- **[Dynamic Icon Colors](icon-colors.md)** - Using icon_color attribute for color-coded dashboards
- **[Actions](actions.md)** - Custom actions (service endpoints) and how to use them
+- **[Chart Examples](chart-examples.md)** - β¨ ApexCharts visualizations with screenshots
- **[Automation Examples](automation-examples.md)** - Ready-to-use automation recipes
- **[Troubleshooting](troubleshooting.md)** - Common issues and solutions
@@ -28,7 +29,8 @@ Welcome to Tibber Prices! This integration provides enhanced electricity price d
- **Statistical analysis** - Trailing/leading 24h averages for context
- **Price ratings** - LOW/NORMAL/HIGH classification based on your thresholds
- **Best/Peak hour detection** - Automatic detection of cheapest/peak periods with configurable filters ([learn how](period-calculation.md))
-- **ApexCharts integration** - Custom actions for beautiful price charts
+- **Beautiful ApexCharts** - Auto-generated chart configurations with dynamic Y-axis scaling ([see examples](chart-examples.md))
+- **Chart metadata sensor** - Dynamic chart configuration for optimal visualization
- **Multi-currency support** - EUR, NOK, SEK with proper minor units (ct, ΓΈre, ΓΆre)
## π Useful Links
diff --git a/docs/user/actions.md b/docs/user/actions.md
index 8f15117..6d99d63 100644
--- a/docs/user/actions.md
+++ b/docs/user/actions.md
@@ -120,11 +120,19 @@ For detailed parameter descriptions, open **Developer Tools β Actions** (the U
>
> **For custom solutions:** Use the `get_chartdata` action directly to build your own charts with full control over the data format and visualization.
-**Purpose:** Generates a basic ApexCharts card YAML configuration example for visualizing electricity prices.
+**Purpose:** Generates a basic ApexCharts card YAML configuration example for visualizing electricity prices with automatic color-coding by price level.
**Prerequisites:**
- [ApexCharts Card](https://github.com/RomRider/apexcharts-card) (required for all configurations)
-- [Config Template Card](https://github.com/iantrich/config-template-card) (required only for rolling window mode without `day` parameter)
+- [Config Template Card](https://github.com/iantrich/config-template-card) (required only for rolling window modes - enables dynamic Y-axis scaling)
+
+**β¨ Key Features:**
+
+- **Automatic Color-Coded Series**: Separate series for each price level (VERY_CHEAP, CHEAP, NORMAL, EXPENSIVE, VERY_EXPENSIVE) or rating (LOW, NORMAL, HIGH)
+- **Dynamic Y-Axis Scaling**: Rolling window modes automatically use `chart_metadata` sensor for optimal Y-axis bounds
+- **Best Price Period Highlights**: Optional vertical bands showing detected best price periods
+- **Translated Labels**: Automatically uses your Home Assistant language setting
+- **Clean Gap Visualization**: Proper NULL insertion for missing data segments
**Quick Example:**
@@ -133,6 +141,8 @@ service: tibber_prices.get_apexcharts_yaml
data:
entry_id: YOUR_ENTRY_ID
day: today # Optional: yesterday, today, tomorrow, rolling_window, rolling_window_autozoom
+ level_type: rating_level # or "level" for 5-level classification
+ highlight_best_price: true # Show best price period overlays
response_variable: apexcharts_config
```
@@ -140,9 +150,76 @@ response_variable: apexcharts_config
- **Fixed days** (`yesterday`, `today`, `tomorrow`): Static 24-hour views, no additional dependencies
- **Rolling Window** (default when omitted or `rolling_window`): Dynamic 48-hour window that automatically shifts between yesterday+today and today+tomorrow based on data availability
+ - **β¨ Includes dynamic Y-axis scaling** via `chart_metadata` sensor
- **Rolling Window (Auto-Zoom)** (`rolling_window_autozoom`): Same as rolling window, but additionally zooms in progressively (2h lookback + remaining time until midnight, graph span decreases every 15 minutes)
+ - **β¨ Includes dynamic Y-axis scaling** via `chart_metadata` sensor
-**Note:** Rolling window modes require [Config Template Card](https://github.com/iantrich/config-template-card) for dynamic behavior.
+**Dynamic Y-Axis Scaling (Rolling Window Modes):**
+
+Rolling window configurations automatically integrate with the `chart_metadata` sensor for optimal chart appearance:
+
+- **Automatic bounds**: Y-axis min/max adjust to data range
+- **No manual configuration**: Works out of the box if sensor is enabled
+- **Fallback behavior**: If sensor is disabled, uses ApexCharts auto-scaling
+- **Real-time updates**: Y-axis adapts when price data changes
+
+**Example: Today's Prices (Static View)**
+
+```yaml
+service: tibber_prices.get_apexcharts_yaml
+data:
+ entry_id: YOUR_ENTRY_ID
+ day: today
+ level_type: rating_level
+response_variable: config
+
+# Use in dashboard:
+type: custom:apexcharts-card
+# ... paste generated config
+```
+
+**Example: Rolling 48h Window (Dynamic View)**
+
+```yaml
+service: tibber_prices.get_apexcharts_yaml
+data:
+ entry_id: YOUR_ENTRY_ID
+ # Omit 'day' for rolling window (or use 'rolling_window')
+ level_type: level # 5-level classification
+ highlight_best_price: true
+response_variable: config
+
+# Use in dashboard:
+type: custom:config-template-card
+entities:
+ - sensor.tibber_home_tomorrow_data
+ - sensor.tibber_home_chart_metadata # For dynamic Y-axis
+card:
+ # ... paste generated config
+```
+
+**Screenshots:**
+
+_Screenshots coming soon for all 4 modes: today, tomorrow, rolling_window, rolling_window_autozoom_
+
+**Level Type Options:**
+
+- **`rating_level`** (default): 3 series (LOW, NORMAL, HIGH) - based on your personal thresholds
+- **`level`**: 5 series (VERY_CHEAP, CHEAP, NORMAL, EXPENSIVE, VERY_EXPENSIVE) - absolute price ranges
+
+**Best Price Period Highlights:**
+
+When `highlight_best_price: true`:
+- Vertical bands overlay the chart showing detected best price periods
+- Tooltip shows "Best Price Period" label when hovering over highlighted areas
+- Only appears when best price periods are configured and detected
+
+**Important Notes:**
+
+- **Config Template Card** is only required for rolling window modes (enables dynamic Y-axis)
+- Fixed day views (`today`, `tomorrow`, `yesterday`) work with ApexCharts Card alone
+- Generated YAML is a starting point - customize colors, styling, features as needed
+- All labels are automatically translated to your Home Assistant language
Use the response in Lovelace dashboards by copying the generated YAML.
diff --git a/docs/user/chart-examples.md b/docs/user/chart-examples.md
new file mode 100644
index 0000000..3cf2a9b
--- /dev/null
+++ b/docs/user/chart-examples.md
@@ -0,0 +1,313 @@
+# Chart Examples
+
+This guide showcases the different chart configurations available through the `tibber_prices.get_apexcharts_yaml` action.
+
+> **Quick Start:** Call the action with your desired parameters, copy the generated YAML, and paste it into your Lovelace dashboard!
+
+## Overview
+
+The integration can generate 4 different chart modes, each optimized for specific use cases:
+
+| Mode | Description | Best For | Dependencies |
+|------|-------------|----------|--------------|
+| **Today** | Static 24h view of today's prices | Quick daily overview | ApexCharts Card |
+| **Tomorrow** | Static 24h view of tomorrow's prices | Planning tomorrow | ApexCharts Card |
+| **Rolling Window** | Dynamic 48h view (today+tomorrow or yesterday+today) | Always-current overview | ApexCharts + Config Template Card |
+| **Rolling Window Auto-Zoom** | Dynamic view that zooms in as day progresses | Real-time focus on remaining day | ApexCharts + Config Template Card |
+
+**Screenshots available for:**
+- β
Today (static) - Representative of all fixed day views
+- β
Rolling Window - Shows dynamic Y-axis scaling
+- β
Rolling Window Auto-Zoom - Shows progressive zoom effect
+
+## All Chart Modes
+
+### 1. Today's Prices (Static)
+
+**When to use:** Simple daily price overview, no dynamic updates needed.
+
+**Dependencies:** ApexCharts Card only
+
+**Generate:**
+```yaml
+service: tibber_prices.get_apexcharts_yaml
+data:
+ entry_id: YOUR_ENTRY_ID
+ day: today
+ level_type: rating_level
+ highlight_best_price: true
+```
+
+**Screenshot:**
+
+
+
+**Key Features:**
+- β
Color-coded price levels (LOW, NORMAL, HIGH)
+- β
Best price period highlights (vertical bands)
+- β
Static 24-hour view (00:00 - 23:59)
+- β
Works with ApexCharts Card alone
+
+**Note:** Tomorrow view (`day: tomorrow`) works identically to Today view, just showing tomorrow's data. All fixed day views (yesterday/today/tomorrow) use the same visualization approach.
+
+---
+
+### 2. Rolling 48h Window (Dynamic)
+
+**When to use:** Always-current view that automatically switches between yesterday+today and today+tomorrow.
+
+**Dependencies:** ApexCharts Card + Config Template Card
+
+**Generate:**
+```yaml
+service: tibber_prices.get_apexcharts_yaml
+data:
+ entry_id: YOUR_ENTRY_ID
+ # Omit 'day' for rolling window
+ level_type: rating_level
+ highlight_best_price: true
+```
+
+**Screenshot:**
+
+
+
+**Key Features:**
+- β
**Dynamic Y-axis scaling** via `chart_metadata` sensor
+- β
Automatic data selection: today+tomorrow (when available) or yesterday+today
+- β
Always shows 48 hours of data
+- β
Updates automatically when tomorrow's data arrives
+- β
Color gradients for visual appeal
+
+**How it works:**
+- Before ~13:00: Shows yesterday + today
+- After ~13:00: Shows today + tomorrow
+- Y-axis automatically adjusts to data range for optimal visualization
+
+---
+
+### 3. Rolling Window Auto-Zoom (Dynamic)
+
+**When to use:** Real-time focus on remaining day - progressively zooms in as day advances.
+
+**Dependencies:** ApexCharts Card + Config Template Card
+
+**Generate:**
+```yaml
+service: tibber_prices.get_apexcharts_yaml
+data:
+ entry_id: YOUR_ENTRY_ID
+ day: rolling_window_autozoom
+ level_type: rating_level
+ highlight_best_price: true
+```
+
+**Screenshot:**
+
+
+
+**Key Features:**
+- β
**Progressive zoom:** Graph span decreases every 15 minutes
+- β
**Dynamic Y-axis scaling** via `chart_metadata` sensor
+- β
Always shows: 2 hours lookback + remaining time until midnight
+- β
Perfect for real-time price monitoring
+- β
Example: At 18:00, shows 16:00 β 00:00 (8h window)
+
+**How it works:**
+- 00:00: Shows full 48h window (same as rolling window)
+- 06:00: Shows 04:00 β midnight (20h window)
+- 12:00: Shows 10:00 β midnight (14h window)
+- 18:00: Shows 16:00 β midnight (8h window)
+- 23:45: Shows 21:45 β midnight (2.25h window)
+
+This creates a "zooming in" effect that focuses on the most relevant remaining time.
+
+---
+
+## Comparison: Level Type Options
+
+### Rating Level (3 series)
+
+Based on **your personal price thresholds** (configured in Options Flow):
+
+- **LOW** (Green): Below your "cheap" threshold
+- **NORMAL** (Blue): Between thresholds
+- **HIGH** (Red): Above your "expensive" threshold
+
+**Best for:** Personal decision-making based on your budget
+
+### Level (5 series)
+
+Based on **absolute price ranges** (calculated from daily min/max):
+
+- **VERY_CHEAP** (Dark Green): Bottom 20%
+- **CHEAP** (Light Green): 20-40%
+- **NORMAL** (Blue): 40-60%
+- **EXPENSIVE** (Orange): 60-80%
+- **VERY_EXPENSIVE** (Red): Top 20%
+
+**Best for:** Objective price distribution visualization
+
+---
+
+## Dynamic Y-Axis Scaling
+
+Rolling window modes (3 & 4) automatically integrate with the `chart_metadata` sensor for optimal visualization:
+
+**Without chart_metadata sensor (disabled):**
+```
+βββββββββββββββββββββββ
+β β β Lots of empty space
+β ___ β
+β ___/ \___ β
+β_/ \_ β
+βββββββββββββββββββββββ€
+0 100 ct
+```
+
+**With chart_metadata sensor (enabled):**
+```
+βββββββββββββββββββββββ
+β ___ β β Y-axis fitted to data
+β ___/ \___ β
+β_/ \_ β
+βββββββββββββββββββββββ€
+18 28 ct β Optimal range
+```
+
+**How to enable:**
+
+1. Enable `sensor.tibber_home_chart_metadata` in entity settings
+2. Add configuration to `configuration.yaml`:
+ ```yaml
+ tibber_prices:
+ chart_metadata_config:
+ day: rolling_window
+ minor_currency: true
+ ```
+3. Restart Home Assistant
+4. Rolling window charts automatically use dynamic scaling!
+
+**Note:** Fixed day views (`today`, `tomorrow`) use ApexCharts' built-in auto-scaling and don't require the metadata sensor.
+
+---
+
+## Best Price Period Highlights
+
+When `highlight_best_price: true`, vertical bands overlay the chart showing detected best price periods:
+
+**Example:**
+```
+Price
+ β
+30β βββββββββββ Normal prices
+ β β β
+25β βββββββ β β Best price period (shaded)
+ β βββββββ β
+20βββββββββββββββββββββββ
+ β ββββββ
+ ββββββββββββββββββββββββ Time
+ 06:00 12:00 18:00
+```
+
+**Features:**
+- Automatic detection based on your configuration (see [Period Calculation Guide](period-calculation.md))
+- Tooltip shows "Best Price Period" label
+- Only appears when periods are configured and detected
+- Can be disabled with `highlight_best_price: false`
+
+---
+
+## Prerequisites
+
+### Required for All Modes
+
+- **[ApexCharts Card](https://github.com/RomRider/apexcharts-card)**: Core visualization library
+ ```bash
+ # Install via HACS
+ HACS β Frontend β Search "ApexCharts Card" β Download
+ ```
+
+### Required for Rolling Window Modes Only
+
+- **[Config Template Card](https://github.com/iantrich/config-template-card)**: Enables dynamic configuration
+ ```bash
+ # Install via HACS
+ HACS β Frontend β Search "Config Template Card" β Download
+ ```
+
+**Note:** Fixed day views (`today`, `tomorrow`) work with ApexCharts Card alone!
+
+---
+
+## Tips & Tricks
+
+### Customizing Colors
+
+Edit the `colors` array in the generated YAML:
+
+```yaml
+apex_config:
+ colors:
+ - "#00FF00" # Change LOW/VERY_CHEAP color
+ - "#0000FF" # Change NORMAL color
+ - "#FF0000" # Change HIGH/VERY_EXPENSIVE color
+```
+
+### Changing Chart Height
+
+Add to the card configuration:
+
+```yaml
+type: custom:apexcharts-card
+graph_span: 48h
+header:
+ show: true
+ title: My Custom Title
+apex_config:
+ chart:
+ height: 400 # Adjust height in pixels
+```
+
+### Combining with Other Cards
+
+Wrap in a vertical stack for dashboard integration:
+
+```yaml
+type: vertical-stack
+cards:
+ - type: entity
+ entity: sensor.tibber_home_current_interval_price
+ - type: custom:apexcharts-card
+ # ... generated chart config
+```
+
+---
+
+## Next Steps
+
+- **[Actions Guide](actions.md)**: Complete documentation of `get_apexcharts_yaml` parameters
+- **[Chart Metadata Sensor](sensors.md#chart-metadata)**: Learn about dynamic Y-axis scaling
+- **[Period Calculation Guide](period-calculation.md)**: Configure best price period detection
+
+---
+
+## Screenshots
+
+### Gallery
+
+1. **Today View (Static)** - Representative of all fixed day views (yesterday/today/tomorrow)
+
+
+
+2. **Rolling Window (Dynamic)** - Shows dynamic Y-axis scaling and 48h window
+
+
+
+ **Recommended for README** - showcases the most impressive features!
+
+3. **Rolling Window Auto-Zoom (Dynamic)** - Shows progressive zoom effect
+
+
+
+**Note:** Tomorrow view is visually identical to Today view (same chart type, just different data), so one static screenshot is sufficient to represent all fixed day modes.
diff --git a/docs/user/sensors.md b/docs/user/sensors.md
index 5612d18..cd8eab2 100644
--- a/docs/user/sensors.md
+++ b/docs/user/sensors.md
@@ -31,6 +31,67 @@ Coming soon...
## Diagnostic Sensors
+### Chart Metadata
+
+**Entity ID:** `sensor.tibber_home_NAME_chart_metadata`
+**Default State:** Disabled (must be manually enabled)
+
+> **β¨ New Feature**: This sensor provides dynamic chart configuration metadata for optimal visualization. Perfect for use with ApexCharts cards!
+
+This diagnostic sensor provides essential chart configuration values as sensor attributes, enabling dynamic Y-axis scaling and optimal chart appearance without manual calculations.
+
+**Key Features:**
+
+- **Dynamic Y-Axis Bounds**: Automatically calculates optimal `yaxis_min` and `yaxis_max` for your price data
+- **Configurable via configuration.yaml**: Set parameters like `day`, `minor_currency`, `resolution` under `tibber_prices.chart_metadata_config`
+- **Automatic Updates**: Refreshes when price data changes (coordinator updates)
+- **Lightweight**: Metadata-only mode (no data processing) for fast response
+- **State Indicator**: Shows `pending` (initialization), `ready` (data available), or `error` (service call failed)
+
+**Attributes:**
+
+- **`timestamp`**: When the metadata was last fetched
+- **`yaxis_min`**: Suggested minimum value for Y-axis (optimal scaling)
+- **`yaxis_max`**: Suggested maximum value for Y-axis (optimal scaling)
+- **`currency`**: Currency code (e.g., "EUR", "NOK")
+- **`resolution`**: Interval duration in minutes (usually 15)
+- **`error`**: Error message if service call failed
+
+**Configuration:**
+
+Add to your `configuration.yaml`:
+
+```yaml
+tibber_prices:
+ chart_metadata_config:
+ day: today # Options: yesterday, today, tomorrow, rolling_window
+ minor_currency: true # Use cents/ΓΈre instead of EUR/NOK
+ resolution: quarter_hourly # Default: quarter_hourly
+```
+
+**Usage with config-template-card:**
+
+The sensor works seamlessly with `config-template-card` to create dynamic ApexCharts configurations:
+
+```yaml
+type: custom:config-template-card
+entities:
+ - sensor.tibber_home_chart_metadata
+card:
+ type: custom:apexcharts-card
+ apex_config:
+ yaxis:
+ min: ${states['sensor.tibber_home_chart_metadata'].attributes.yaxis_min}
+ max: ${states['sensor.tibber_home_chart_metadata'].attributes.yaxis_max}
+ # ... rest of your chart config
+```
+
+**Integration with get_apexcharts_yaml Service:**
+
+The `tibber_prices.get_apexcharts_yaml` service **automatically uses this sensor** for dynamic Y-axis scaling in `rolling_window` and `rolling_window_autozoom` modes! See the [Actions Guide](actions.md) for details.
+
+---
+
### Chart Data Export
**Entity ID:** `sensor.tibber_home_NAME_chart_data_export`
diff --git a/images/charts/README.md b/images/charts/README.md
new file mode 100644
index 0000000..c43bafd
--- /dev/null
+++ b/images/charts/README.md
@@ -0,0 +1,32 @@
+# Chart Screenshots
+
+This directory contains screenshots of the different chart configurations available through `tibber_prices.get_apexcharts_yaml`.
+
+## Files:
+
+- β
`today.png` - Static view of today's prices (representative of all fixed day views)
+- β
`rolling-window.png` - Dynamic 48h rolling window with Y-axis scaling
+- β
`rolling-window-autozoom.png` - Auto-zoom view with progressive zoom
+
+**Note:** Tomorrow view is visually identical to today view, so one static screenshot covers all fixed day modes (yesterday/today/tomorrow).
+
+## Screenshot Guidelines:
+
+When capturing screenshots:
+
+1. Use a clean Home Assistant dashboard (no other cards visible)
+2. Capture during a day with interesting price variations (show the chart at work!)
+3. Include both light and dark mode versions if possible
+4. Make sure best price period highlights are visible (if enabled)
+5. Capture at a resolution that's readable when embedded in docs (at least 1200px width)
+
+## Recommended for README.md:
+
+Use `rolling_window.png` in the main README.md as it shows:
+- β
Dynamic 48h window (impressive!)
+- β
Color-coded series (visual appeal)
+- β
Dynamic Y-axis scaling (key feature)
+- β
Best price period highlights (useful overlay)
+- β
Gradient effect (polished look)
+
+This showcases the most advanced features at a glance!