Energy Horizon 1.1.0

What's new – Highlights

1. Advanced offset (ISO-8601 Standard)

We have introduced the ability to precisely define the start of a time window down to the day or even the hour. Starting with version 1.1.0, the offset duration parameter supports ISO-8601 notation (e.g., P4M4D), allowing you to combine different time units in a single entry. For example, P3Y6M4DT12H represents a duration of "three years, six months, four days, twelve hours".

• Backward Compatibility: The old notation (e.g., +4d / +4M) is still supported, but we recommend switching to the ISO standard for greater flexibility.

Example:
If your annual billing period starts on May 15th (which is 4 months and 14 days after the start of the year), configure the card as follows:

time_window:
  step: 1y
  duration: 1y
  anchor: start_of_year
  # Offset: +4 months from 1st month and +14 days from 1st day = 15th May
  offset: P4M14D

2. New Interpretation Logic — Consumption vs. Production

The card can now correctly interpret not only energy consumption but also production (e.g., from solar PV). You can now clearly define the nature of your data in both the visual editor and YAML, which directly affects data presentation and trend color coding.

• Options: consumption (default) or production.

YAML:

interpretation: production
# Default: consumption

3. Intelligent Comments and Consistent Narrative

We have improved the text generation algorithm (narrative). Comments below the chart now dynamically adapt to custom time steps (step). If your time window does not align with a full calendar month, the card will use precise phrasing consistent with your specific configuration.

Example: With step: 1w, instead of generic phrases, you will see a summary referring directly to seven-day intervals.

YAML:

time_window:
  step: 1w
  duration: 1w
  anchor: start_of_week

4. Neutral State (Deadband) Threshold Configuration

We have introduced a "deadband" (neutral zone) for trends. You can now define a percentage threshold below which any change in value is treated as a neutral state (indicating no significant increase or decrease).

Example:

neutral_interpretation: 10
# Changes within ±10% will be marked as neutral
# default value when not defined ±2%

Technical changlog

Added

• Compound ISO 8601 offset (time_window.offset): the offset field now accepts a full ISO 8601 duration string (P4M4D, -P2M, P1M15D, etc.), so you can set precise custom window starts (e.g. a billing / fiscal year from 5 May with offset: P4M4D from start_of_year). Windows are built with Luxon DateTime.plus(Duration) — end-of-month clamping is deterministic. Sub-hour offsets are rejected with a configuration error. The legacy +1d / +3M-style form remains supported as a shim to the equivalent P form (deprecated; will be removed later). Implementation: single parser src/card/time-windows/parse-time-window-offset.ts (FR-900-Q); Vitest coverage in tests/unit/time-windows-offset-iso.test.ts and extended time-windows-{merge-validate,presets-golden,resolve}.test.ts (SC-900-6 / US-900 stories).
• Narrative engine (step-based copy): the comparison comment now picks the period phrase from merged YAML time_window.step (via classifyComparisonStep), not from resolved window geometry — so billing offsets and non-calendar steps (1w, 16d, 3M, …) match the configured intent. Translation layout is text_summary.{consumption|production|generic}.{higher|lower|similar|neutral_band} plus text_summary.period.{day|week|month|year|reference} and shared text_summary.insufficient_data / text_summary.no_reference; optional entity keys fall back to mandatory text_summary.generic.*. Contributor grammar notes: src/translations/CONTEXT.md.
• interpretation (consumption | production, default consumption): aligns the comparison narrative, trend icon, and chart delta segment with whether the entity represents usage (less is better) or generation (more is better). Delta chip numeric signs stay arithmetic; Forecast | Total copy is unchanged.
• neutral_interpretation: optional non-negative percent T (default 2). When the chip’s signed percent p satisfies |p| ≤ T, narrative and chart delta use neutral “similar” styling. YAML-only in this release; the visual editor preserves the key via shallow merge.
• Visual editor control for interpretation (Consumption / Production).
• Translations (en, pl, de, fr) for production-oriented narrative, neutral-band text, and editor labels.

Changed

• Interpretation in the comparison comment (behavior / copy): the narrative no longer infers “month vs year” from resolved window geometry (consecutive calendar months). It uses merged time_window.step and maps interpretation: production / consumption to the new text_summary.* key layout with text_summary.generic.* fallback — so production and consumption keep the correct semantic polarity and the period phrase (day / week / month / year / reference) matches the configured step and any offset, without spurious “last year” phrasing. Insufficient comparison data uses text_summary.insufficient_data, not text_summary.no_reference.

Learn More

Full Changelog: 1.0.2...1.1.0-beta