feat(config-flow): isolate oversized displays in generated dashboard YAML

The "Copy dashboard YAML" export listed every configured display as a
flat list of cards, so a landscape reTerminal E1003 (1872x1404) ended up
squeezed into the same row as much smaller Kindle cards. Switch the
generator to a Lovelace `sections` layout: entries whose width or height
is more than 1.5x the median (or the smaller of two, when there are
too few entries for a median) get their own full-width section, while
similarly sized entries continue to share one row.

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

Author: cryptomilk

README.md

@@ -109,7 +109,9 @@ After setup, click **Configure** on the integration entry to:
 - **Add / remove push target** - manage TRMNL webhook URLs
 - **Copy card YAML** - get the Lovelace card snippet for this device
 - **Copy dashboard YAML** - get a full dashboard YAML with cards for all
-  configured devices
+  configured devices, using a `sections` layout that gives any
+  disproportionately large display (e.g. a landscape reTerminal E1003) its
+  own row instead of squeezing it in next to smaller cards
 
 ## Dashboard setup
 

custom_components/eink_dashboard/config_flow.py

@@ -17,6 +17,7 @@
 from __future__ import annotations
 
 import os
+import statistics
 from copy import deepcopy
 from typing import TYPE_CHECKING, Any
 from urllib.parse import urlparse
@@ -318,6 +319,137 @@ def _screen_portion_options(
     ]
 
 
+# An entry's width or height exceeding this ratio versus the baseline
+# marks it as "large" for _split_large_entries. Chosen so a landscape
+# reTerminal E1003 (1872x1404) next to a portrait Kindle Paperwhite
+# (758x1024) is isolated, while a Kindle Paperwhite 4 (1072x1448)
+# stays grouped with a Kindle Paperwhite.
+_LARGE_SIZE_RATIO = 1.5
+
+
+def _entry_dimensions(entry: ConfigEntry) -> tuple[int, int]:
+    """Return an entry's stored card dimensions.
+
+    Args:
+        entry: A config entry for the ``eink_dashboard`` domain.
+
+    Returns:
+        A (width, height) tuple, falling back to the default canvas
+        size if the entry has not stored dimensions yet. Each value
+        is clamped to a minimum of 1 to guard against hand-edited
+        storage containing zero, which would otherwise cause a
+        division by zero in ``_split_large_entries``.
+    """
+    return (
+        max(entry.options.get("width", DEFAULT_WIDTH), 1),
+        max(entry.options.get("height", DEFAULT_HEIGHT), 1),
+    )
+
+
+def _split_large_entries(
+    entries: list[ConfigEntry],
+) -> tuple[list[ConfigEntry], list[ConfigEntry]]:
+    """Split entries into normal-sized and oversized groups.
+
+    An entry is "large" when its width or height exceeds
+    ``_LARGE_SIZE_RATIO`` times the baseline for that dimension, so
+    generated dashboard YAML can give it its own full-width section
+    instead of squeezing it into a shared row. The baseline is the
+    median width/height across all entries, or the minimum when
+    there are fewer than three entries (a median is meaningless
+    with so few samples and would flag the larger of just two
+    entries as an outlier).
+
+    Args:
+        entries: Config entries for the ``eink_dashboard`` domain.
+
+    Returns:
+        A tuple of (normal-sized entries, large entries), each
+        preserving the input order.
+    """
+    dims = [_entry_dimensions(e) for e in entries]
+    if len(entries) >= 3:
+        baseline_w = statistics.median(w for w, _ in dims)
+        baseline_h = statistics.median(h for _, h in dims)
+    else:
+        baseline_w = min((w for w, _ in dims), default=DEFAULT_WIDTH)
+        baseline_h = min((h for _, h in dims), default=DEFAULT_HEIGHT)
+
+    normal: list[ConfigEntry] = []
+    large: list[ConfigEntry] = []
+    for entry, (width, height) in zip(entries, dims, strict=True):
+        ratio = max(width / baseline_w, height / baseline_h)
+        (large if ratio > _LARGE_SIZE_RATIO else normal).append(entry)
+    return normal, large
+
+
+def _grid_section(
+    entries: list[ConfigEntry],
+    full_width: bool = False,
+) -> str:
+    """Build one ``type: grid`` section block for the dashboard YAML.
+
+    Args:
+        entries: Config entries whose cards appear in this section.
+        full_width: When ``True``, each card gets
+            ``grid_options: columns: full`` so it spans the entire
+            view width instead of sharing the row.
+
+    Returns:
+        A YAML string fragment for a single sections-view grid.
+    """
+    # entry_id is always an HA-generated hex/ULID string, so it
+    # never needs YAML escaping here.
+    suffix = (
+        "\n            grid_options:\n              columns: full"
+        if full_width
+        else ""
+    )
+    cards = "\n".join(
+        "          - type: custom:eink-dashboard-card\n"
+        f"            config_entry: {e.entry_id}{suffix}"
+        for e in entries
+    )
+    return (
+        f"      - type: grid\n        cards:\n{cards}\n        column_span: 10"
+    )
+
+
+def _build_dashboard_yaml(entries: list[ConfigEntry]) -> str:
+    """Build a Lovelace ``sections`` view YAML for all given entries.
+
+    Normal-sized entries share one grid section so they lay out side
+    by side; entries much larger than the rest (see
+    ``_split_large_entries``) each get their own full-width section.
+
+    Args:
+        entries: Config entries for the ``eink_dashboard`` domain.
+            The caller (``async_step_copy_dashboard_yaml``) always
+            passes at least one entry, since the options flow's own
+            config entry is always part of the domain's entries.
+
+    Returns:
+        A YAML string for a full Lovelace dashboard view.
+    """
+    normal, large = _split_large_entries(entries)
+
+    sections = []
+    if normal:
+        sections.append(_grid_section(normal))
+    sections.extend(_grid_section([e], full_width=True) for e in large)
+
+    sections_yaml = "\n".join(sections)
+    return (
+        "views:\n"
+        "  - type: sections\n"
+        "    max_columns: 10\n"
+        "    sections:\n"
+        f"{sections_yaml}\n"
+        "    title: E-Ink Dashboards\n"
+        "    cards: []"
+    )
+
+
 class EinkDashboardConfigFlow(ConfigFlow, domain=DOMAIN):
     """Multi-step config flow for creating a new dashboard entry."""
 
@@ -671,12 +803,7 @@ async def async_step_copy_dashboard_yaml(
         if user_input is not None:
             return await self.async_step_init()
         entries = self.hass.config_entries.async_entries(DOMAIN)
-        cards = "\n".join(
-            f"      - type: custom:eink-dashboard-card\n"
-            f"        config_entry: {e.entry_id}"
-            for e in entries
-        )
-        yaml = f"views:\n  - title: E-Ink Dashboards\n    cards:\n{cards}"
+        yaml = _build_dashboard_yaml(entries)
         return self.async_show_form(
             step_id="copy_dashboard_yaml",
             data_schema=vol.Schema({}),

tests/test_config_flow.py

@@ -19,6 +19,7 @@
 
 import pytest
 import voluptuous as vol
+import yaml  # via homeassistant -> pyyaml
 from homeassistant.config_entries import SOURCE_USER
 from homeassistant.data_entry_flow import FlowResultType
 from homeassistant.helpers import entity_registry as er
@@ -1897,6 +1898,73 @@ async def test_copy_dashboard_yaml_shows_all_entries(
         assert "aaa111" in yaml
         assert "bbb222" in yaml
         assert "eink-dashboard-card" in yaml
+        assert "type: sections" in yaml
+
+    async def test_copy_dashboard_yaml_groups_similar_sizes_together(
+        self, hass: HomeAssistant
+    ) -> None:
+        # Entries with similar card sizes share one grid section and
+        # get no explicit grid_options, since the default sizing
+        # already fits them side by side. _make_options_flow's own
+        # backing entry (default 758x1024) is also included in the
+        # entries list and contributes to the baseline calculation.
+        flow = await _make_options_flow(hass, {"webhook_urls": []})
+        entry_a = MockConfigEntry(
+            domain=DOMAIN,
+            entry_id="kindle_pw",
+            options={"width": 758, "height": 1024},
+        )
+        entry_a.add_to_hass(hass)
+        entry_b = MockConfigEntry(
+            domain=DOMAIN,
+            entry_id="kindle_pw4",
+            options={"width": 1072, "height": 1448},
+        )
+        entry_b.add_to_hass(hass)
+        result = await flow.async_step_copy_dashboard_yaml(None)
+
+        yaml = result["description_placeholders"]["yaml"]
+        assert yaml.count("type: grid") == 1
+        assert "grid_options" not in yaml
+
+    async def test_copy_dashboard_yaml_isolates_oversized_entry(
+        self, hass: HomeAssistant
+    ) -> None:
+        # An entry much larger than the others (e.g. a landscape
+        # reTerminal E1003 next to portrait Kindles) gets its own
+        # full-width grid section instead of sharing a row.
+        # _make_options_flow's own backing entry (default 758x1024)
+        # is also included in the entries list and contributes to
+        # the median baseline, making this a 4-entry median.
+        flow = await _make_options_flow(hass, {"webhook_urls": []})
+        entry_a = MockConfigEntry(
+            domain=DOMAIN,
+            entry_id="kindle_pw",
+            options={"width": 758, "height": 1024},
+        )
+        entry_a.add_to_hass(hass)
+        entry_b = MockConfigEntry(
+            domain=DOMAIN,
+            entry_id="kindle_oasis",
+            options={"width": 1264, "height": 1680},
+        )
+        entry_b.add_to_hass(hass)
+        entry_huge = MockConfigEntry(
+            domain=DOMAIN,
+            entry_id="reterminal_e1003",
+            options={"width": 1872, "height": 1404},
+        )
+        entry_huge.add_to_hass(hass)
+        result = await flow.async_step_copy_dashboard_yaml(None)
+
+        yaml = result["description_placeholders"]["yaml"]
+        assert yaml.count("type: grid") == 2
+        assert yaml.count("grid_options") == 1
+        assert yaml.count("columns: full") == 1
+        sections = yaml.split("type: grid")[1:]
+        huge_section = next(s for s in sections if "reterminal_e1003" in s)
+        assert "kindle_pw" not in huge_section
+        assert "kindle_oasis" not in huge_section
 
     async def test_copy_dashboard_yaml_submit_returns_to_init(
         self, hass: HomeAssistant
@@ -1908,6 +1976,116 @@ async def test_copy_dashboard_yaml_submit_returns_to_init(
         assert result["type"] is FlowResultType.MENU
         assert result["step_id"] == "init"
 
+    async def test_copy_dashboard_yaml_parses_to_valid_structure(
+        self, hass: HomeAssistant
+    ) -> None:
+        # Generated YAML is syntactically valid and matches the
+        # expected Lovelace sections-view structure: a shared grid
+        # for normal-sized entries and a full-width grid per
+        # oversized entry, each holding the right card config.
+        # _make_options_flow's own backing entry (default
+        # 758x1024) is also included in the entries list.
+        flow = await _make_options_flow(hass, {"webhook_urls": []})
+        entry_a = MockConfigEntry(
+            domain=DOMAIN,
+            entry_id="kindle_pw",
+            options={"width": 758, "height": 1024},
+        )
+        entry_a.add_to_hass(hass)
+        entry_huge = MockConfigEntry(
+            domain=DOMAIN,
+            entry_id="reterminal_e1003",
+            options={"width": 1872, "height": 1404},
+        )
+        entry_huge.add_to_hass(hass)
+        result = await flow.async_step_copy_dashboard_yaml(None)
+
+        raw = result["description_placeholders"]["yaml"]
+        doc = yaml.safe_load(raw)
+        view = doc["views"][0]
+        assert view["type"] == "sections"
+        assert view["max_columns"] == 10
+        assert view["title"] == "E-Ink Dashboards"
+        assert "path" not in view
+        sections = view["sections"]
+        assert len(sections) == 2
+
+        normal_section = sections[0]
+        assert normal_section["type"] == "grid"
+        assert normal_section["column_span"] == 10
+        assert len(normal_section["cards"]) == 2
+        assert all(
+            c["type"] == "custom:eink-dashboard-card"
+            for c in normal_section["cards"]
+        )
+
+        large_section = sections[1]
+        assert large_section["type"] == "grid"
+        assert len(large_section["cards"]) == 1
+        large_card = large_section["cards"][0]
+        assert large_card["config_entry"] == "reterminal_e1003"
+        assert large_card["grid_options"] == {"columns": "full"}
+
+    async def test_copy_dashboard_yaml_isolates_multiple_oversized(
+        self, hass: HomeAssistant
+    ) -> None:
+        # Two entries much larger than the normals each get their
+        # own full-width grid section rather than sharing one.
+        # _make_options_flow's own backing entry (default
+        # 758x1024) is also included in the entries list.
+        flow = await _make_options_flow(hass, {"webhook_urls": []})
+        for entry_id in ("normal_a", "normal_b"):
+            entry = MockConfigEntry(
+                domain=DOMAIN,
+                entry_id=entry_id,
+                options={"width": 758, "height": 1024},
+            )
+            entry.add_to_hass(hass)
+        for entry_id, width, height in (
+            ("large_a", 1872, 1404),
+            ("large_b", 2560, 1600),
+        ):
+            entry = MockConfigEntry(
+                domain=DOMAIN,
+                entry_id=entry_id,
+                options={"width": width, "height": height},
+            )
+            entry.add_to_hass(hass)
+        result = await flow.async_step_copy_dashboard_yaml(None)
+
+        raw = result["description_placeholders"]["yaml"]
+        assert raw.count("type: grid") == 3
+        assert raw.count("grid_options") == 2
+        assert raw.count("columns: full") == 2
+
+    async def test_copy_dashboard_yaml_exact_threshold_is_normal(
+        self, hass: HomeAssistant
+    ) -> None:
+        # An entry at exactly 1.5x the baseline stays in the normal
+        # group, since _split_large_entries uses a strict > compare.
+        # _make_options_flow's own backing entry (default
+        # 758x1024) is also included in the entries list.
+        flow = await _make_options_flow(hass, {"webhook_urls": []})
+        entry_anchor = MockConfigEntry(
+            domain=DOMAIN,
+            entry_id="anchor",
+            options={"width": 758, "height": 1024},
+        )
+        entry_anchor.add_to_hass(hass)
+        # Exactly 1.5x the 758x1024 baseline: 758*1.5=1137,
+        # 1024*1.5=1536.
+        entry_boundary = MockConfigEntry(
+            domain=DOMAIN,
+            entry_id="boundary",
+            options={"width": 1137, "height": 1536},
+        )
+        entry_boundary.add_to_hass(hass)
+        result = await flow.async_step_copy_dashboard_yaml(None)
+
+        raw = result["description_placeholders"]["yaml"]
+        assert raw.count("type: grid") == 1
+        assert "grid_options" not in raw
+
     async def test_display_settings_persists_entry_options(
         self, hass: HomeAssistant
     ) -> None: