feat(heading): add text alignment option

Weekday-style headings (Monday vs. Friday) shift position as their
text length changes; right-aligning keeps the end of the text at a
consistent spot. Adds heading_align ("left"/"right") to the Heading
widget, following the same anchor pattern as the Entity widget's
name_align — right-aligned text anchors to the space left of any
placed badges, or the right content edge when there are none, while
the icon stays left-anchored.

Fixes #84

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

Author: cryptomilk

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

@@ -69,6 +69,7 @@ export const WIDGET_TYPES: Record<string, WidgetTypeMeta> = {
       h: 56,
       heading: "",
       heading_style: "title",
+      heading_align: "left",
       icon_style: "none",
       card_style: DEFAULT_CARD_STYLE,
     },
@@ -428,6 +429,26 @@ function nameAlignSelector(): HaFormSchema {
   };
 }
 
+/**
+ * Heading text alignment dropdown selector.
+ *
+ * @returns A single ha-form schema entry.
+ */
+function headingAlignSelector(): HaFormSchema {
+  return {
+    name: "heading_align",
+    default: "left",
+    selector: {
+      select: {
+        options: [
+          { value: "left", label: "Left" },
+          { value: "right", label: "Right" },
+        ],
+      },
+    },
+  };
+}
+
 /**
  * Icon style dropdown selector.
  *
@@ -903,7 +924,11 @@ export const SCHEMAS: Record<
       flatten: true,
       title: "Appearance",
       icon: "mdi:palette",
-      schema: [cardStyleSelector(), iconStyleSelector("none")],
+      schema: [
+        cardStyleSelector(),
+        iconStyleSelector("none"),
+        headingAlignSelector(),
+      ],
     },
   ],
 
@@ -1553,6 +1578,7 @@ export const LABELS: Record<string, string> = {
   unit: "Unit",
   heading: "Heading",
   heading_style: "Heading style",
+  heading_align: "Heading alignment",
   badges: "Badges",
   card_style: "Card style",
   icon_style: "Icon style",

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

@@ -585,6 +585,15 @@ export interface HeadingWidget extends WidgetBase {
    * - ``"subtitle"`` — smaller Roboto Regular in gray.
    */
   heading_style?: "title" | "subtitle";
+  /**
+   * Horizontal text alignment.
+   * - ``"left"`` — text starts at the icon-derived left edge
+   *   (default).
+   * - ``"right"`` — text ends at the space left of any badges, or
+   *   the right content edge when there are none.  The icon, if
+   *   present, stays left-anchored.
+   */
+  heading_align?: "left" | "right";
   /** MDI icon name rendered to the left of the text (e.g. "mdi:home"). */
   icon?: string;
   /**

custom_components/eink_dashboard/templates/heading.svg.j2

@@ -23,6 +23,7 @@
   font-weight="{{ font_weight }}"
   font-size="{{ font_sz }}"
   dominant-baseline="central"
+  text-anchor="{{ text_anchor }}"
   fill="{{ text_fill }}">{{ heading }}</text>
 {%- endif -%}
 {%- for badge in badges -%}

custom_components/eink_dashboard/widgets/heading.py

@@ -80,10 +80,21 @@ def _build_heading_context(
     Badges are resolved right-to-left from the right edge; any badge
     that would overlap the heading text is silently omitted.
 
+    ``heading_align`` controls the heading text's horizontal anchor:
+
+    - ``"left"`` — text starts at the icon-derived left edge
+      (default).
+    - ``"right"`` — text ends at the space left of any placed
+      badges, or the right content edge when there are none.  The
+      icon, if present, stays left-anchored.  If the text is too
+      wide to fit in that space, its left edge is clamped to the
+      icon-derived left edge instead of drawing over the icon.
+
     Args:
         widget: Widget config dict.  Recognised keys:
             ``heading`` (display text, default ``""``),
             ``heading_style`` (``"title"`` / ``"subtitle"``),
+            ``heading_align`` (``"left"`` / ``"right"``),
             ``icon`` (MDI icon name, e.g. ``"mdi:home"``),
             ``icon_style`` (``"none"`` / ``"filled"`` /
             ``"outlined"``),
@@ -111,6 +122,7 @@ def _build_heading_context(
     svg_h = _widget_dim(widget, "h", DEFAULT_ROW_H)
     heading_text: str = widget.get("heading", "")
     heading_style: str = widget.get("heading_style", "title")
+    heading_align: str = widget.get("heading_align", "left")
     icon_override = widget.get("icon")
     icon_style: str = widget.get("icon_style", "none")
     raw_badges = widget.get("badges", [])
@@ -160,7 +172,7 @@ def _build_heading_context(
             # edge.
             icon_glyph_x = content_left
             icon_glyph_y = svg_h // 2 - glyph_sz // 2
-            text_x = content_left + glyph_sz + m.inner_gap
+            min_text_x = content_left + glyph_sz + m.inner_gap
         else:
             # Circle style: glyph is centred inside the circle.
             r = m.icon_dia // 2
@@ -170,9 +182,9 @@ def _build_heading_context(
             icon_fill = color_to_hex(COLOR_GRAY)
             icon_glyph_x = icon_cx - glyph_sz // 2
             icon_glyph_y = icon_cy - glyph_sz // 2
-            text_x = content_left + m.icon_dia + m.inner_gap
+            min_text_x = content_left + m.icon_dia + m.inner_gap
     else:
-        text_x = content_left
+        min_text_x = content_left
 
     text_y = svg_h // 2
 
@@ -235,12 +247,15 @@ def _build_heading_context(
     # Position badges right-to-left.  Once a badge cannot fit
     # (its left edge would overlap the heading text), it and
     # all remaining badges to its left in config order are
-    # dropped.
+    # dropped.  The overlap boundary is always the icon-derived
+    # left edge (``min_text_x``), regardless of ``heading_align``,
+    # since that is where left-aligned text starts and where
+    # right-aligned text is clamped to below.
     badge_right = svg_w - r_inset - rpad
     rendered_badges: list[dict[str, object]] = []
     for bd in reversed(badge_data):
         new_right = badge_right - bd.total_w
-        if new_right < text_x + m.inner_gap:
+        if new_right < min_text_x + m.inner_gap:
             break
         badge_cy = svg_h // 2
         rendered_badges.insert(
@@ -257,6 +272,23 @@ def _build_heading_context(
         )
         badge_right = new_right - m.inner_gap
 
+    # Right alignment anchors the text to the space left of any
+    # placed badges (or the right content edge when there are none),
+    # rather than the icon-derived left edge.  If the heading text is
+    # wide enough that anchoring it there would push its left edge
+    # past ``min_text_x``, clamp the anchor so the text never draws
+    # over the icon — matching the left-aligned case, where text
+    # simply grows rightward from ``min_text_x`` instead.
+    text_x = min_text_x
+    text_anchor = "start"
+    if heading_align == "right":
+        text_anchor = "end"
+        text_x = badge_right
+        if heading_text:
+            heading_font = _load_font(font_sz, medium=is_title)
+            text_w = round(heading_font.getlength(heading_text))
+            text_x = max(text_x - text_w, min_text_x) + text_w
+
     has_content = bool(heading_text) or bool(icon_svg) or bool(rendered_badges)
 
     if not has_content:
@@ -294,6 +326,7 @@ def _build_heading_context(
         "text_fill": text_fill,
         "text_x": text_x,
         "text_y": text_y,
+        "text_anchor": text_anchor,
         # Badges (pre-positioned, empty list when none fit).
         "badges": rendered_badges,
         "badge_font_sz": badge_font_sz,

tests/test_render_heading.py

@@ -527,6 +527,172 @@ def test_heading_icon_style_none_is_default(self) -> None:
         without = render_dashboard([base], self._config())
         assert with_none == without
 
+    # ── Alignment tests ───────────────────────────────
+
+    def test_heading_align_left_is_default(self) -> None:
+        # Omitting heading_align produces byte-identical output to
+        # heading_align="left".
+        base = {
+            "type": "heading",
+            "x": 0,
+            "y": 0,
+            "w": 400,
+            "h": 56,
+            "heading": "Section",
+        }
+        with_left = render_dashboard(
+            [{**base, "heading_align": "left"}], self._config()
+        )
+        without = render_dashboard([base], self._config())
+        assert with_left == without
+
+    def test_heading_align_right_changes_output(self) -> None:
+        # heading_align="right" changes the rendered output relative
+        # to the default left alignment.
+        base = {
+            "type": "heading",
+            "x": 0,
+            "y": 0,
+            "w": 400,
+            "h": 56,
+            "heading": "Monday",
+        }
+        left = render_dashboard([base], self._config())
+        right = render_dashboard(
+            [{**base, "heading_align": "right"}], self._config()
+        )
+        assert left != right, (
+            "heading_align='right' should change rendered output"
+        )
+
+    def test_heading_align_right_text_near_right_edge(self) -> None:
+        # Right-aligned text has its rightmost ink near the right
+        # content edge of the widget.
+        m = _compute_metrics(56)
+        widgets = [
+            {
+                "type": "heading",
+                "x": 0,
+                "y": 0,
+                "w": 400,
+                "h": 56,
+                "heading": "Mon",
+                "heading_align": "right",
+            }
+        ]
+        img = render_to_image(widgets, self._config())
+        right_edge = 400 - m.padding
+        bb = content_bbox(img, 0, 0, 400, 56)
+        assert bb is not None, "right-aligned heading should draw content"
+        assert bb[2] >= right_edge - 5, (
+            "heading_align='right' should place text near right edge"
+        )
+
+    def test_heading_align_right_with_icon(self) -> None:
+        # With an icon present, the icon stays left-anchored while
+        # the text anchors to the right edge.
+        m = _compute_metrics(56)
+        widgets = [
+            {
+                "type": "heading",
+                "x": 0,
+                "y": 0,
+                "w": 400,
+                "h": 56,
+                "heading": "Mon",
+                "icon": "mdi:home",
+                "heading_align": "right",
+            }
+        ]
+        img = render_to_image(widgets, self._config())
+        # Icon draws dark pixels on the left.
+        assert_has_dark_pixels(
+            img, m.padding, 4, m.padding + 30, 52, threshold=200
+        )
+        # Text draws dark pixels near the right edge.
+        right_edge = 400 - m.padding
+        bb = content_bbox(img, 100, 0, 400, 56)
+        assert bb is not None
+        assert bb[2] >= right_edge - 5, (
+            "right-aligned text should reach the right edge"
+        )
+
+    def test_heading_align_right_long_text_clamps_to_icon(self) -> None:
+        # A heading too wide to fit between the icon and the right
+        # edge must not draw over the icon; its left edge clamps to
+        # the icon-derived boundary instead of extending further
+        # left, as it would with an unbounded right anchor.
+        m = _compute_metrics(56)
+        widgets = [
+            {
+                "type": "heading",
+                "x": 0,
+                "y": 0,
+                "w": 400,
+                "h": 56,
+                "heading": "A Really Very Long Heading Text That Overflows",
+                "icon": "mdi:home",
+                "heading_align": "right",
+            }
+        ]
+        img = render_to_image(widgets, self._config())
+        # Icon still draws dark pixels on the left.
+        assert_has_dark_pixels(
+            img, m.padding, 4, m.padding + 30, 52, threshold=200
+        )
+        # The gap between the icon and the text's clamped left edge
+        # stays white — text does not creep left over the icon.
+        glyph_sz = max(10, m.font_primary)
+        icon_right = m.padding + glyph_sz
+        min_text_x = icon_right + m.inner_gap
+        assert_all_white(img, icon_right, 0, min_text_x, 56)
+
+    def test_heading_align_right_with_badges(self) -> None:
+        # With badges present, right-aligned text anchors to the left
+        # of the badge area rather than the widget edge — badges
+        # change where the text lands.
+        base = {
+            "type": "heading",
+            "x": 0,
+            "y": 0,
+            "w": 400,
+            "h": 56,
+            "heading": "A",
+            "heading_align": "right",
+            "badges": ["sensor.temperature"],
+        }
+        without_badges = render_dashboard(
+            [{**base, "badges": []}], self._config()
+        )
+        with_badges = render_dashboard([base], self._config())
+        assert without_badges != with_badges, (
+            "badges should shift right-aligned text anchor leftward"
+        )
+
+    def test_heading_align_right_with_card_border(self) -> None:
+        # With card_style="border", right-aligned text respects the
+        # border's right inset rather than the widget's raw edge.
+        m = _compute_metrics(56)
+        widgets = [
+            {
+                "type": "heading",
+                "x": 0,
+                "y": 0,
+                "w": 400,
+                "h": 56,
+                "heading": "Mon",
+                "heading_align": "right",
+                "card_style": "border",
+            }
+        ]
+        img = render_to_image(widgets, self._config())
+        right_edge = 400 - m.padding
+        bb = content_bbox(img, m.padding, 4, 400 - m.padding, 52)
+        assert bb is not None
+        assert bb[2] >= right_edge - 5, (
+            "right-aligned text should respect border inset"
+        )
+
     # ── Badge tests ───────────────────────────────────
 
     def test_heading_badges_change_output(self) -> None: