feat(graph): add start_time to anchor the graph to a fixed time today

The graph window could only be a rolling hours_to_show range relative
to the latest data point, with no way to pin it to a fixed time of
day (e.g. show only today from midnight). Add a start_time config
key ("HH:MM") resolved via the new _resolve_start_cutoff() helper
(today's date, per datetime.now(), combined with the parsed time),
threaded through _extract_entity_points() as a start_cutoff override
that replaces the rolling hours_to_show window when set.

Addresses #88

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: cryptomilk

custom_components/eink_dashboard/frontend/src/eink-dashboard-editor.ts

@@ -1372,6 +1372,10 @@ export const SCHEMAS: Record<
             },
           ],
         },
+        {
+          name: "start_time",
+          selector: { time: {} },
+        },
         {
           name: "aggregate_func",
           default: "avg",
@@ -1619,6 +1623,7 @@ export const LABELS: Record<string, string> = {
   attribute_timestamp_key: "Timestamp key",
   attribute_value_key: "Value key",
   hours_to_show: "Hours to show",
+  start_time: "Start time",
   detail: "Detail",
   limits_min: "Y-axis minimum",
   limits_max: "Y-axis maximum",

custom_components/eink_dashboard/frontend/src/types/ha.d.ts

@@ -1005,8 +1005,19 @@ export interface GraphWidget extends WidgetBase {
    * Required when {@link data_source} is ``"attribute"``.
    */
   attribute_value_key?: string;
-  /** History window in hours. Default: 24. */
+  /**
+   * History window in hours.  Default: 24.  Ignored when
+   * ``start_time`` is set.
+   */
   hours_to_show?: number;
+  /**
+   * Time-of-day string in ``"HH:MM"`` format (e.g. ``"00:00"``) that
+   * anchors the graph window to a fixed time today instead of a
+   * rolling ``hours_to_show`` window.  Empty/unparsable values are
+   * ignored.  If the time has not occurred yet today, the graph
+   * shows no data until it does.
+   */
+  start_time?: string;
   /**
    * Number of data points per hour retained after bucketing.
    * Each hour is split into ``1 / points_per_hour`` fixed-width

custom_components/eink_dashboard/widgets/graph.py

@@ -697,6 +697,52 @@ def _fix_header_layout(
     return x_off + lpad, svg_w - r_inset - rpad
 
 
+def _resolve_start_cutoff(
+    start_time_str: str, now: datetime.datetime
+) -> float | None:
+    """Resolve a ``start_time`` config string to today's Unix timestamp.
+
+    ``now`` is treated as local time: HA sets the system timezone to
+    match its configured timezone, so local time is the correct frame
+    of reference for server-side rendering (see the same assumption
+    in ``conditions.py``'s time-condition evaluation).
+
+    Args:
+        start_time_str: Time-of-day string parseable by
+            ``datetime.time.fromisoformat`` (e.g. ``"00:00"``), or
+            empty to disable the fixed start time.
+        now: Current local datetime; only its date is used, so tests
+            can pass a fixed value for deterministic results.
+
+    Returns:
+        Unix timestamp for ``now``'s date at the given time, or
+        ``None`` when ``start_time_str`` is empty or unparsable. If
+        the resolved timestamp is still in the future relative to
+        ``now``, it is returned as-is (the graph will show no data
+        until that time is reached later today) and a warning is
+        logged.
+    """
+    if not start_time_str:
+        return None
+    try:
+        parsed = datetime.time.fromisoformat(start_time_str)
+    except ValueError:
+        _LOGGER.warning(
+            "Graph widget 'start_time' %r is not a valid HH:MM time; "
+            "ignoring it",
+            start_time_str,
+        )
+        return None
+    cutoff = datetime.datetime.combine(now.date(), parsed)
+    if cutoff > now:
+        _LOGGER.warning(
+            "Graph widget 'start_time' %s has not occurred yet "
+            "today; the graph will show no data until then",
+            start_time_str,
+        )
+    return cutoff.timestamp()
+
+
 def _combined_state_text(
     entity_descs: list[dict[str, object]],
     states: dict[str, Any],
@@ -1207,19 +1253,26 @@ def _extract_entity_points(
     hours_to_show: int,
     points_per_hour: float,
     aggregate_func: str,
+    start_cutoff: float | None = None,
 ) -> list[tuple[float, float]]:
     """Extract and aggregate history data for one entity descriptor.
 
     Reads the entity's raw history from ``states_dict``, filters to
-    the ``hours_to_show`` time window, strips non-numeric entries, and
-    buckets the result via ``_aggregate_history``.
+    the ``hours_to_show`` time window (or ``start_cutoff`` when
+    given), strips non-numeric entries, and buckets the result via
+    ``_aggregate_history``.
 
     Args:
         desc: Entity descriptor dict from ``_normalize_entities()``.
         states_dict: States dict from the display config.
-        hours_to_show: History window in hours.
+        hours_to_show: History window in hours.  Ignored when
+            ``start_cutoff`` is not ``None``.
         points_per_hour: Target data density for bucketing.
         aggregate_func: Bucket reduction function name.
+        start_cutoff: Optional fixed Unix timestamp cutoff (from the
+            widget's ``start_time`` setting).  When given, only
+            history entries at or after this timestamp are kept,
+            replacing the rolling ``hours_to_show`` window entirely.
 
     Returns:
         Sorted oldest-to-newest list of ``(timestamp, value)`` pairs,
@@ -1232,24 +1285,32 @@ def _extract_entity_points(
         list(state.get("history", [])) if isinstance(state, dict) else []
     )
     if raw_hist:
-        t_latest = max(
-            (
-                float(str(e.get("lu", 0)))
-                for e in raw_hist
-                if math.isfinite(float(str(e.get("lu", 0))))
-            ),
-            default=None,
-        )
-        if t_latest is None:
-            raw_hist = []
-        else:
-            cutoff = t_latest - hours_to_show * 3600
+        if start_cutoff is not None:
             raw_hist = [
                 e
                 for e in raw_hist
                 if math.isfinite(float(str(e.get("lu", 0))))
-                and float(str(e.get("lu", 0))) > cutoff
+                and float(str(e.get("lu", 0))) >= start_cutoff
             ]
+        else:
+            t_latest = max(
+                (
+                    float(str(e.get("lu", 0)))
+                    for e in raw_hist
+                    if math.isfinite(float(str(e.get("lu", 0))))
+                ),
+                default=None,
+            )
+            if t_latest is None:
+                raw_hist = []
+            else:
+                cutoff = t_latest - hours_to_show * 3600
+                raw_hist = [
+                    e
+                    for e in raw_hist
+                    if math.isfinite(float(str(e.get("lu", 0))))
+                    and float(str(e.get("lu", 0))) > cutoff
+                ]
     numeric: list[tuple[float, float]] = []
     for entry in raw_hist:
         s = entry.get("s", "")
@@ -1487,7 +1548,14 @@ def _build_graph_context(
             ``name`` (display name override),
             ``icon`` (MDI icon name, e.g. ``"mdi:thermometer"``),
             ``unit`` (unit string override),
-            ``hours_to_show`` (history window in hours; default 24),
+            ``hours_to_show`` (history window in hours; default 24;
+            ignored when ``start_time`` is set),
+            ``start_time`` (time-of-day string, e.g. ``"00:00"``,
+            parseable by ``datetime.time.fromisoformat``; when set,
+            the graph shows data from this time today onward instead
+            of a rolling ``hours_to_show`` window; empty/unparsable
+            values are ignored; if the time has not occurred yet
+            today, the graph shows no data until it does),
             ``points_per_hour`` (data points per hour; default 0.5,
             giving one point per 2-hour bucket),
             ``aggregate_func`` (``"avg"``, ``"min"``, ``"max"``,
@@ -1558,6 +1626,9 @@ def _build_graph_context(
     svg_w = _widget_dim(widget, "w", config["width"] - x)
 
     hours_to_show: int = int(float(widget.get("hours_to_show", 24)))
+    start_cutoff = _resolve_start_cutoff(
+        str(widget.get("start_time", "")), datetime.datetime.now()
+    )
     points_per_hour: float = float(widget.get("points_per_hour", 0.5))
     aggregate_func: str = str(widget.get("aggregate_func", "avg"))
     group_by: str = str(widget.get("group_by", "interval"))
@@ -1696,6 +1767,7 @@ def _build_graph_context(
                     hours_to_show,
                     points_per_hour,
                     aggregate_func,
+                    start_cutoff,
                 )
             )
 

tests/test_render_graph.py

@@ -510,6 +510,59 @@ def test_graph_hours_to_show_affects_data(self) -> None:
         )
         assert svg_full != svg_short
 
+    def test_graph_start_time_filters_out_earlier_points(self) -> None:
+        # start_time anchors the window to a fixed time today,
+        # overriding hours_to_show entirely: points before the fixed
+        # start time are excluded, raising the auto-computed Y-axis
+        # minimum from 10.0 (all points) to 20.0 (only points at/after
+        # the start time).  History timestamps are built relative to
+        # datetime.now() so the test is deterministic regardless of
+        # when it runs.
+        import datetime as dt
+
+        now = dt.datetime.now()
+        midday = now.replace(hour=12, minute=0, second=0, microsecond=0)
+        history = [
+            {
+                "s": "10.0",
+                "lu": (midday - dt.timedelta(hours=2)).timestamp(),
+            },
+            {
+                "s": "15.0",
+                "lu": (midday - dt.timedelta(hours=1)).timestamp(),
+            },
+            {
+                "s": "20.0",
+                "lu": (midday + dt.timedelta(hours=1)).timestamp(),
+            },
+            {
+                "s": "25.0",
+                "lu": (midday + dt.timedelta(hours=2)).timestamp(),
+            },
+        ]
+        states: dict[str, dict[str, object]] = {
+            "sensor.temperature": {
+                **MOCK_GRAPH_STATES["sensor.temperature"],
+                "history": history,
+            }
+        }
+        common = {
+            "hours_to_show": 48,
+            "points_per_hour": 2,
+            "smoothing": False,
+            "show_labels": True,
+        }
+        svg_no_start = render_widget_svg(
+            self._base_widget(**common), self._config(states=states)
+        )
+        svg_with_start = render_widget_svg(
+            self._base_widget(**common, start_time="12:00"),
+            self._config(states=states),
+        )
+        assert "10.0" in svg_no_start
+        assert "10.0" not in svg_with_start
+        assert "20.0" in svg_with_start
+
     def test_graph_aggregate_avg_accepted(self) -> None:
         # aggregate_func="avg" is accepted without error and produces a
         # graph element.
@@ -2876,3 +2929,118 @@ def test_graph_thresholds_fill_gradient_uses_lighter_colors(
             fill_val = int(fill_hex[1:3], 16)
             # Fill is lighter (higher value) than stroke.
             assert fill_val >= stroke_val
+
+    # ── _resolve_start_cutoff unit tests ───────────────────────────────
+
+    def test_resolve_start_cutoff_empty_string_is_none(self) -> None:
+        # An empty start_time string disables the fixed start time.
+        import datetime as dt
+
+        from custom_components.eink_dashboard.widgets.graph import (
+            _resolve_start_cutoff,
+        )
+
+        now = dt.datetime(2026, 6, 11, 15, 0)
+        assert _resolve_start_cutoff("", now) is None
+
+    def test_resolve_start_cutoff_invalid_string_is_none(self) -> None:
+        # An unparsable start_time string is ignored rather than
+        # raising, degrading gracefully to "no fixed start time".
+        import datetime as dt
+
+        from custom_components.eink_dashboard.widgets.graph import (
+            _resolve_start_cutoff,
+        )
+
+        result = _resolve_start_cutoff(
+            "not-a-time", dt.datetime(2026, 6, 11, 15, 0)
+        )
+        assert result is None
+
+    def test_resolve_start_cutoff_combines_today_with_time(self) -> None:
+        # A valid "HH:MM" string is combined with now's date to
+        # produce today's timestamp at that time.
+        import datetime as dt
+
+        from custom_components.eink_dashboard.widgets.graph import (
+            _resolve_start_cutoff,
+        )
+
+        now = dt.datetime(2026, 6, 11, 15, 0)
+        result = _resolve_start_cutoff("06:30", now)
+        expected = dt.datetime(2026, 6, 11, 6, 30).timestamp()
+        assert result == expected
+
+    def test_resolve_start_cutoff_invalid_string_logs_warning(
+        self, caplog: pytest.LogCaptureFixture
+    ) -> None:
+        # An unparsable start_time string logs a warning so a typo in
+        # the widget config isn't silently invisible.
+        import datetime as dt
+        import logging
+
+        from custom_components.eink_dashboard.widgets.graph import (
+            _resolve_start_cutoff,
+        )
+
+        with caplog.at_level(logging.WARNING):
+            _resolve_start_cutoff(
+                "not-a-time", dt.datetime(2026, 6, 11, 15, 0)
+            )
+        assert "not a valid" in caplog.text
+
+    def test_resolve_start_cutoff_future_time_logs_warning(
+        self, caplog: pytest.LogCaptureFixture
+    ) -> None:
+        # When start_time has not occurred yet today, the timestamp
+        # is still returned as-is (the graph anchors to today's date
+        # only; it does not roll back to yesterday), but a warning is
+        # logged since the graph will show no data until then.
+        import datetime as dt
+        import logging
+
+        from custom_components.eink_dashboard.widgets.graph import (
+            _resolve_start_cutoff,
+        )
+
+        now = dt.datetime(2026, 6, 11, 8, 0)
+        with caplog.at_level(logging.WARNING):
+            result = _resolve_start_cutoff("18:00", now)
+        expected = dt.datetime(2026, 6, 11, 18, 0).timestamp()
+        assert result == expected
+        assert "has not occurred yet today" in caplog.text
+
+    def test_extract_entity_points_start_cutoff_is_inclusive(self) -> None:
+        # A history entry exactly at start_cutoff is kept, matching
+        # the widget docstring's "from this time today onward"
+        # (inclusive) wording.  Points are spaced an hour apart with
+        # points_per_hour=1 so each lands in its own bucket and the
+        # aggregated value is unchanged, making it safe to assert on
+        # the returned values directly.
+        from custom_components.eink_dashboard.widgets.graph import (
+            _extract_entity_points,
+        )
+
+        cutoff = 0.0
+        desc = {"entity": "sensor.temperature"}
+        states_dict = {
+            "sensor.temperature": {
+                "history": [
+                    {"s": "1.0", "lu": cutoff - 3600},
+                    {"s": "2.0", "lu": cutoff},
+                    {"s": "3.0", "lu": cutoff + 3600},
+                ]
+            }
+        }
+        points = _extract_entity_points(
+            desc,
+            states_dict,
+            hours_to_show=24,
+            points_per_hour=1,
+            aggregate_func="avg",
+            start_cutoff=cutoff,
+        )
+        values = [v for _, v in points]
+        assert 1.0 not in values
+        assert 2.0 in values
+        assert 3.0 in values