doc: Add comprehensive chart examples and screenshots for tibber_prices integration

- Created a new documentation file `chart-examples.md` detailing various chart configurations available through the `tibber_prices.get_apexcharts_yaml` action.
- Included descriptions, dependencies, and YAML generation examples for four chart modes: Today's Prices, Rolling 48h Window, and Rolling Window Auto-Zoom.
- Added a section on dynamic Y-axis scaling and best price period highlights.
- Established prerequisites for using the charts, including required cards and customization tips.
- Introduced a new `README.md` in the images/charts directory to document available chart screenshots and guidelines for capturing them.

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

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.
 

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:**
+
+<img src="../../images/charts/today.png" width="800" alt="Today's Prices - Static 24h View">
+
+**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:**
+
+<img src="../../images/charts/rolling-window.png" width="800" alt="Rolling 48h Window with Dynamic Y-Axis Scaling">
+
+**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:**
+
+<img src="../../images/charts/rolling-window-autozoom.png" width="800" alt="Rolling Window Auto-Zoom - Progressive Zoom Effect">
+
+**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)
+
+   <img src="../../images/charts/today.png" width="600" alt="Today View">
+
+2. **Rolling Window (Dynamic)** - Shows dynamic Y-axis scaling and 48h window
+
+   <img src="../../images/charts/rolling-window.png" width="600" alt="Rolling Window">
+
+   **Recommended for README** - showcases the most impressive features!
+
+3. **Rolling Window Auto-Zoom (Dynamic)** - Shows progressive zoom effect
+
+   <img src="../../images/charts/rolling-window-autozoom.png" width="600" alt="Rolling Window Auto-Zoom">
+
+**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.

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`

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!